{ "components": { "headers": { "CacheControlNoStore": { "description": "Always `no-store`. Object and link state is live data and is never cacheable.", "schema": { "type": "string" } } }, "parameters": { "IdempotencyKey": { "description": "Opaque idempotency token (Stripe-shape). Repeated POSTs with the same key replay the original response within the cache TTL rather than creating a duplicate object.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "minLength": 1, "type": "string" } } }, "responses": { "Forbidden": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The bearer authenticated but does not hold the scope this operation requires." }, "NotFound": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No such object in the caller's tenant — which is also the answer when it exists in another tenant, by design." }, "Unprocessable": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The request parsed but a validator refused it. The envelope's `code` names which rule." } }, "schemas": { "ActionTypeSummary": { "properties": { "api_name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "display_name": { "type": "string" }, "effects": { "items": { "$ref": "#/components/schemas/EffectSummary" }, "type": "array" }, "parameter_count": { "minimum": 0, "type": "integer" }, "target_object_type": { "description": "Bound target object type for targeted actions. Untargeted actions (creates) leave it null.", "nullable": true, "type": "string" } }, "required": [ "api_name", "display_name", "parameter_count", "effects" ], "type": "object" }, "AgentAuthoringMetric": { "description": "A canonical (highest-version) metric offered to the author, trimmed to what a builder needs to reference and label one.", "properties": { "description": { "nullable": true, "type": "string" }, "grain": { "description": "The metric's native temporal grain.", "enum": [ "day", "week", "month", "quarter", "year" ], "type": "string" }, "name": { "type": "string" }, "version": { "minimum": 0, "type": "integer" } }, "required": [ "name", "grain", "version" ], "type": "object" }, "AgentAuthoringPickList": { "properties": { "action_types": { "items": { "$ref": "#/components/schemas/ActionTypeSummary" }, "type": "array" }, "function_types": { "items": { "$ref": "#/components/schemas/FunctionTypeSummary" }, "type": "array" }, "metrics": { "items": { "$ref": "#/components/schemas/AgentAuthoringMetric" }, "type": "array" }, "object_types": { "items": { "$ref": "#/components/schemas/ObjectTypeSummary" }, "type": "array" }, "registry_entry_id": { "format": "uuid", "type": "string" } }, "required": [ "registry_entry_id", "object_types", "action_types", "function_types", "metrics" ], "type": "object" }, "BookingPaceCaptureRequest": { "properties": { "as_of": { "description": "The property-local business day to capture, for a house whose business time is not the clock's — a replayed or simulated booking log captured at each day's close. Refused (`422`) in the future, and refused once any reservation of the property was booked or cancelled on a later day: the live tables are that day's end-of-day book only until then. Absent, the clock picks the day as described above.", "format": "date", "type": "string" }, "property_id": { "description": "Property whose current business day to snapshot.", "format": "uuid", "type": "string" } }, "required": [ "property_id" ], "type": "object" }, "BookingPaceCaptureResponse": { "properties": { "captured": { "description": "False when that day's snapshot already existed — snapshot rows are immutable, so nothing was written.", "type": "boolean" }, "property_id": { "format": "uuid", "type": "string" }, "snapshot_date_local": { "description": "The property-local business day the capture targeted.", "format": "date", "type": "string" } }, "required": [ "property_id", "snapshot_date_local", "captured" ], "type": "object" }, "BookingPaceResponse": { "properties": { "arrival_date": { "description": "The stay (occupancy) date of this curve.", "format": "date", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rows": { "description": "Ordered by `snapshot_date_local` ascending.", "items": { "$ref": "#/components/schemas/BookingPaceRow" }, "type": "array" }, "segment": { "enum": [ "total", "transient", "group", "contract" ], "type": "string" } }, "required": [ "property_id", "arrival_date", "segment", "rows" ], "type": "object" }, "BookingPaceRow": { "properties": { "adr_otb": { "description": "`revenue_otb / rooms_otb`; null when zero rooms are on the books.", "format": "decimal", "type": [ "string", "null" ] }, "captured_at": { "format": "date-time", "type": "string" }, "days_before_arrival": { "type": "integer" }, "pickup": { "description": "Present only when `horizons` was requested: one entry per horizon, in request order.", "items": { "properties": { "horizon_days": { "type": "integer" }, "revenue": { "format": "decimal", "type": [ "string", "null" ] }, "rooms": { "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "horizon_days" ], "type": "object" }, "type": "array" }, "revenue_otb": { "description": "Exact decimal rendered as a string.", "format": "decimal", "type": "string" }, "revenue_picked_up_1d": { "format": "decimal", "type": [ "string", "null" ] }, "rooms_otb": { "format": "int64", "type": "integer" }, "rooms_picked_up_1d": { "description": "OTB delta vs. the prior day's snapshot; null on a curve's first snapshot.", "format": "int64", "type": [ "integer", "null" ] }, "snapshot_date_local": { "format": "date", "type": "string" } }, "required": [ "snapshot_date_local", "days_before_arrival", "rooms_otb", "revenue_otb", "captured_at" ], "type": "object" }, "CardAuthorisationRequest": { "additionalProperties": false, "properties": { "amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "The hold to take. The folio's own currency is not assumed — a guest may be held in the card's currency, and guessing here charges the wrong number." }, "contested_network_signal_id": { "description": "A Watchtower answer that refused this card (`refused_by_watchtower`, its `fraud_network_signal_id`) and that the desk has since contested with `contest_fraud_network_signal` because it believes the guest. A block the network gives again takes the hold to review (`risk_band` high) instead of refusing it.", "format": "uuid", "type": "string" }, "customer": { "description": "The saved-card customer, when a raw token names one.", "type": "string" }, "payment_card_id": { "description": "A card already on file. The ordinary path, and the one OPERA and Mews both take.", "format": "uuid", "type": "string" }, "payment_method": { "description": "A processor token collected by a hosted surface and used once without being kept — the fallback for a guarantee nobody will draw on again. Never a PAN.", "type": "string" }, "purpose": { "description": "Why the hold is placed, recorded on the payment as `hold_purpose` (OPERA's source of authorisation). Omitted, the route says it from the folio: `check_in` on a stay's folio, `booking` on the booking's own account, `incidentals` on a folio with no booking behind it.", "enum": [ "booking", "check_in", "top_up", "re_placement", "incidentals", "no_show", "post_stay", "other" ], "type": "string" } }, "required": [ "amount" ], "type": "object" }, "CardAuthorisationResponse": { "properties": { "authorisation_expires_at": { "description": "When the hold lapses at the processor, when it says. Absent is not proof of no expiry.", "format": "date-time", "type": [ "string", "null" ] }, "fraud_risk_assessment_id": { "description": "The assessment this authorisation was scored against. Always present: every hold is scored, including the ones that sail through.", "format": "uuid", "type": "string" }, "payment_id": { "format": "uuid", "type": "string" }, "risk_band": { "description": "The band that decided whether a human had to look.", "type": "string" } }, "required": [ "payment_id", "fraud_risk_assessment_id", "risk_band" ], "type": "object" }, "CardCaptureResponse": { "properties": { "amount_received_minor": { "description": "What actually moved, in minor units — not necessarily what was held.", "format": "int64", "type": "integer" }, "payment_id": { "format": "uuid", "type": "string" } }, "required": [ "payment_id", "amount_received_minor" ], "type": "object" }, "CardRefundRequest": { "additionalProperties": false, "properties": { "refund_amount": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "Partial refunds are ordinary; the kernel computes the remaining refundable balance from the legs already recorded." }, "refund_reason": { "enum": [ "duplicate", "fraudulent", "requested_by_customer", "reservation_cancelled", "deposit_return", "service_recovery", "overcharge_correction", "no_show_policy_exception", "package_component_refund", "membership_cancellation", "chargeback_prevention", "other" ], "type": "string" } }, "required": [ "refund_amount", "refund_reason" ], "type": "object" }, "CardRefundResponse": { "properties": { "original_payment_id": { "format": "uuid", "type": "string" }, "refund_payment_id": { "description": "The new negative-amount leg. Proposal 0019's shape: a refund is a second payment, not an edit of the first.", "format": "uuid", "type": "string" }, "status": { "description": "`pending` until the processor confirms it on the webhook.", "type": "string" } }, "required": [ "refund_payment_id", "original_payment_id" ], "type": "object" }, "CardVoidRequest": { "additionalProperties": false, "properties": { "void_reason": { "description": "The kernel's word. The hospitality reasons have no processor equivalent and travel as `abandoned` while surviving in full on the row.", "enum": [ "duplicate", "fraudulent", "requested_by_customer", "abandoned", "review_declined", "authorisation_expired", "reservation_cancelled", "guest_disputed_pre_arrival", "released_at_departure" ], "type": "string" } }, "required": [ "void_reason" ], "type": "object" }, "CardVoidResponse": { "properties": { "payment_id": { "format": "uuid", "type": "string" }, "void_reason": { "enum": [ "duplicate", "fraudulent", "requested_by_customer", "abandoned", "review_declined", "authorisation_expired", "reservation_cancelled", "guest_disputed_pre_arrival", "released_at_departure" ], "type": "string" } }, "required": [ "payment_id", "void_reason" ], "type": "object" }, "CheckCardPaymentRequest": { "additionalProperties": false, "properties": { "amount": { "$ref": "#/components/schemas/Money", "description": "The part of the check's balance this card pays, tip excluded: more than zero, at most `balance_due`, in the check's currency." }, "device_id": { "description": "The registered `hospitality.device` the guest pays on. Must be `active` and carry the Adyen `POIID` in `vendor_device_ref`.", "format": "uuid", "type": "string" }, "tip_mode": { "default": "none", "description": "`on_terminal` asks the guest for a tip on the terminal (`tenderOption=AskGratuity`); the tip comes back in `AmountsResp.TipAmount` and is recorded as the payment's `tip`.", "enum": [ "none", "on_terminal" ], "type": "string" } }, "required": [ "device_id", "amount" ], "type": "object" }, "CheckCardPaymentResponse": { "properties": { "amount": { "$ref": "#/components/schemas/Money" }, "check": { "properties": { "balance_due": { "$ref": "#/components/schemas/Money" }, "status": { "enum": [ "open", "settled" ], "type": "string" } }, "required": [ "balance_due", "status" ], "type": "object" }, "idempotent_replay": { "description": "`true` on a cached `Idempotency-Key` replay.", "type": "boolean" }, "payment_id": { "description": "The `hospitality.check_payment` recorded.", "format": "uuid", "type": "string" }, "psp_reference": { "description": "Adyen's `pspReference` for the payment.", "type": [ "string", "null" ] }, "tip": { "$ref": "#/components/schemas/Money" } }, "required": [ "payment_id", "amount", "tip", "check" ], "type": "object" }, "CollectCancellationFeeRequest": { "additionalProperties": false, "properties": { "payment_card_id": { "description": "Charge this card specifically. Omit it and the route picks the card bound to the reservation, then any active consented card the guest has on file.", "format": "uuid", "type": "string" } }, "type": "object" }, "CollectCancellationFeeResponse": { "properties": { "amount": { "description": "What this collection asked for, as a decimal string: the booking hold's share (`hold_amount`) and the card's — the fee, capped at what the booking's account still owed after the deposit on it. On `collected`, what was taken.", "type": "string" }, "awaiting_guest": { "description": "True when the outcome is `authentication_required` and the card rail recorded the pending authentication: a payment request with reason `authentication_required` (`authentication_for = cancellation_fee`) carries the house's deadline, and its page goes to the guest at a house with the chase on. Paid, it collects the fee.", "type": "boolean" }, "currency": { "type": "string" }, "failure_reason": { "description": "Why it did not, in the processor's own words.", "type": [ "string", "null" ] }, "fee": { "description": "The posted cancellation fee (`cancellation_fee_amount`), as a decimal string.", "type": "string" }, "hold_amount": { "description": "What the booking's hold has paid toward the fee, as a decimal string (`0` when there was none).", "type": "string" }, "outcome": { "description": "`authentication_required` is not a decline — the issuer wants SCA, the fee is still owed, and it is collectable once the guest authenticates.", "enum": [ "collected", "authentication_required", "uncollectible" ], "type": "string" }, "paid_by": { "description": "Which path paid a collected fee — `booking_hold`, `stored_card` or `booking_hold_and_stored_card`.", "type": [ "string", "null" ] }, "psp_reference": { "description": "The processor's reference when the card was charged — the only handle that survives into a dispute.", "type": [ "string", "null" ] }, "reservation_id": { "format": "uuid", "type": "string" } }, "required": [ "reservation_id", "outcome", "amount", "currency", "fee" ], "type": "object" }, "CollectNoShowFeeRequest": { "additionalProperties": false, "properties": { "payment_card_id": { "description": "Charge this card specifically. Omit it and the route picks the card bound to the reservation, then any active consented card the guest has on file.", "format": "uuid", "type": "string" } }, "type": "object" }, "CollectNoShowFeeResponse": { "properties": { "amount": { "description": "The assessed fee, as a decimal string.", "type": "string" }, "awaiting_guest": { "description": "True when the outcome is `authentication_required` and the card rail recorded the pending authentication (`payment.authentication_pending`): a payment request with reason `authentication_required` carries the house's deadline, and its page goes to the guest at a house with the chase on (`set_sca_chase`). Paid, it collects the fee.", "type": "boolean" }, "currency": { "type": "string" }, "failure_reason": { "description": "Why it did not, in the processor's own words.", "type": [ "string", "null" ] }, "hold_amount": { "description": "What the booking's hold has paid toward the fee, as a decimal string (`0` when there was none).", "type": "string" }, "outcome": { "description": "`authentication_required` is not a decline — the issuer wants SCA, the fee is still owed at full value, and it is collectable once the guest authenticates.", "enum": [ "collected", "authentication_required", "uncollectible" ], "type": "string" }, "paid_by": { "description": "Which path paid a collected fee — `booking_hold`, `stored_card` or `booking_hold_and_stored_card`: the booking's own card hold (captured for the fee, the rest released), the stored card off-session, or the hold and then the card for what the hold could not cover.", "type": [ "string", "null" ] }, "psp_reference": { "description": "The processor's reference when money moved — the only handle that survives into a dispute.", "type": [ "string", "null" ] }, "reservation_id": { "format": "uuid", "type": "string" } }, "required": [ "reservation_id", "outcome", "amount", "currency" ], "type": "object" }, "CreateWebhookSubscriptionRequest": { "additionalProperties": false, "properties": { "filter": { "$ref": "#/components/schemas/WebhookSubscriptionFilter" }, "start_position": { "description": "Where the cursor starts. `beginning` replays from `seq = 0` (full backfill); `now` / `head` skips historic events and delivers only what arrives after the subscription is created. Default `now`.", "enum": [ "beginning", "now", "head" ] }, "url": { "description": "Receiver URL. HTTPS only (HTTP allowed only against loopback hosts for dev/test). Max 2048 chars.", "format": "uri", "type": "string" } }, "required": [ "url" ], "type": "object" }, "DataTypeArray": { "properties": { "element": { "$ref": "#/components/schemas/DataTypeSummary" }, "kind": { "const": "array", "enum": [ "array" ], "type": "string" } }, "required": [ "kind", "element" ], "type": "object" }, "DataTypeBool": { "properties": { "kind": { "const": "bool", "enum": [ "bool" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, "DataTypeCurrency": { "properties": { "kind": { "const": "currency", "enum": [ "currency" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, "DataTypeDate": { "properties": { "kind": { "const": "date", "enum": [ "date" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, "DataTypeDateTime": { "properties": { "kind": { "const": "date_time", "enum": [ "date_time" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, "DataTypeDecimal": { "properties": { "kind": { "const": "decimal", "enum": [ "decimal" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, "DataTypeDuration": { "properties": { "kind": { "const": "duration", "enum": [ "duration" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, "DataTypeEnum": { "properties": { "kind": { "const": "enum", "enum": [ "enum" ], "type": "string" }, "values": { "description": "Allowed string values for the enum.", "items": { "type": "string" }, "type": "array" } }, "required": [ "kind", "values" ], "type": "object" }, "DataTypeGeoPoint": { "properties": { "kind": { "const": "geo_point", "enum": [ "geo_point" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, "DataTypeInt": { "properties": { "kind": { "const": "int", "enum": [ "int" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, "DataTypeJson": { "properties": { "kind": { "const": "json", "enum": [ "json" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, "DataTypeMoney": { "properties": { "kind": { "const": "money", "enum": [ "money" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, "DataTypeReference": { "properties": { "kind": { "const": "reference", "enum": [ "reference" ], "type": "string" }, "object_type": { "description": "Api_name of the referenced object type.", "type": "string" } }, "required": [ "kind", "object_type" ], "type": "object" }, "DataTypeString": { "properties": { "kind": { "const": "string", "enum": [ "string" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, "DataTypeStruct": { "properties": { "fields": { "items": { "$ref": "#/components/schemas/StructFieldSummary" }, "type": "array" }, "kind": { "const": "struct", "enum": [ "struct" ], "type": "string" } }, "required": [ "kind", "fields" ], "type": "object" }, "DataTypeSummary": { "description": "Compact, runtime-friendly summary of a property's data type. Mirrors `aerandil_ontology::DataType` (the source-of-truth Rust enum) and is structurally recursive through the `array` and `struct` variants — terminates at leaf types.", "discriminator": { "mapping": { "array": "#/components/schemas/DataTypeArray", "bool": "#/components/schemas/DataTypeBool", "currency": "#/components/schemas/DataTypeCurrency", "date": "#/components/schemas/DataTypeDate", "date_time": "#/components/schemas/DataTypeDateTime", "decimal": "#/components/schemas/DataTypeDecimal", "duration": "#/components/schemas/DataTypeDuration", "enum": "#/components/schemas/DataTypeEnum", "geo_point": "#/components/schemas/DataTypeGeoPoint", "int": "#/components/schemas/DataTypeInt", "json": "#/components/schemas/DataTypeJson", "money": "#/components/schemas/DataTypeMoney", "reference": "#/components/schemas/DataTypeReference", "string": "#/components/schemas/DataTypeString", "struct": "#/components/schemas/DataTypeStruct", "text": "#/components/schemas/DataTypeText" }, "propertyName": "kind" }, "oneOf": [ { "$ref": "#/components/schemas/DataTypeBool" }, { "$ref": "#/components/schemas/DataTypeInt" }, { "$ref": "#/components/schemas/DataTypeDecimal" }, { "$ref": "#/components/schemas/DataTypeMoney" }, { "$ref": "#/components/schemas/DataTypeCurrency" }, { "$ref": "#/components/schemas/DataTypeString" }, { "$ref": "#/components/schemas/DataTypeText" }, { "$ref": "#/components/schemas/DataTypeDate" }, { "$ref": "#/components/schemas/DataTypeDateTime" }, { "$ref": "#/components/schemas/DataTypeDuration" }, { "$ref": "#/components/schemas/DataTypeGeoPoint" }, { "$ref": "#/components/schemas/DataTypeJson" }, { "$ref": "#/components/schemas/DataTypeEnum" }, { "$ref": "#/components/schemas/DataTypeArray" }, { "$ref": "#/components/schemas/DataTypeStruct" }, { "$ref": "#/components/schemas/DataTypeReference" } ] }, "DataTypeText": { "properties": { "kind": { "const": "text", "enum": [ "text" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, "DeskPasscodeRequest": { "additionalProperties": false, "properties": { "employee_id": { "description": "Who is at the desk, as typed at the lock screen (the `staff_member` business key). Exactly one of `employee_id` and `staff_member_id`.", "type": "string" }, "passcode": { "description": "The staff member's passcode — the same one the floor handset takes.", "type": "string" }, "staff_member_id": { "description": "Who is at the desk, when the desk already knows (a step-up).", "format": "uuid", "type": "string" }, "unlock_token": { "description": "The shift's unlock token, from opening the session. It grants nothing alone and is never a bearer.", "type": "string" } }, "required": [ "unlock_token", "passcode" ], "type": "object" }, "DeskSessionResponse": { "allOf": [ { "$ref": "#/components/schemas/TokenResponse" }, { "properties": { "desk_session_id": { "format": "uuid", "type": "string" }, "idle_lock_secs": { "description": "Idle seconds after which the desk locks (`AERANDIL_DESK_IDLE_LOCK`).", "type": "integer" }, "outlet_id": { "description": "The outlet whose till the session is; absent at the front desk.", "format": "uuid", "type": "string" }, "properties": { "description": "The houses the person the bearer runs as may hold the desk at — one per front-office staff record claiming their identity — the choices `POST /v1/desk/sessions/{id}/move` takes.", "items": { "format": "uuid", "type": "string" }, "type": "array" }, "property_id": { "format": "uuid", "type": "string" }, "role": { "description": "The desk role the scope vector came from (the F&B roles at a till).", "enum": [ "front_desk", "front_office_manager", "food_beverage_server", "food_beverage_manager" ], "type": "string" }, "shift_ends_at": { "description": "When the shift — and every token minted for it — ends.", "format": "date-time", "type": "string" }, "staff_member_id": { "description": "The staff member the bearer runs as — its `User` principal.", "format": "uuid", "type": "string" }, "step_up_secs": { "description": "Seconds a step-up is honoured for (`AERANDIL_DESK_STEP_UP_TTL`).", "type": "integer" }, "step_up_until": { "description": "Until when this bearer carries a step-up proof. Absent on the sign-in's own bearer: an identity-provider session may be silently re-used, so it is not a proof.", "format": "date-time", "type": "string" }, "switched": { "description": "On a passcode proof: whether the desk changed hands.", "type": "boolean" }, "unlock_token": { "description": "Only when opening: what a locked desk keeps to come back by passcode.", "type": "string" } }, "required": [ "desk_session_id", "property_id", "staff_member_id", "role", "shift_ends_at", "idle_lock_secs", "step_up_secs", "properties" ], "type": "object" } ] }, "DispatchInvoiceRequest": { "additionalProperties": false, "properties": { "cc": { "items": { "format": "email", "type": "string" }, "type": "array" }, "message": { "description": "Replaces the covering note's body.", "type": "string" }, "to": { "description": "Overrides the address on the document's recipient snapshot.", "format": "email", "type": "string" } }, "type": "object" }, "DispatchInvoiceResponse": { "properties": { "channel": { "enum": [ "email" ], "type": "string" }, "invoice_id": { "format": "uuid", "type": "string" }, "message_id": { "description": "The `Message-ID` stamped on the way out — ours, not the relay's, so a delivery complaint traces back to a send.", "type": "string" }, "sent_at": { "format": "date-time", "type": "string" }, "to": { "format": "email", "type": "string" } }, "required": [ "invoice_id", "channel", "to", "sent_at" ], "type": "object" }, "EffectCreate": { "properties": { "kind": { "const": "create", "enum": [ "create" ], "type": "string" }, "object_type": { "type": "string" } }, "required": [ "kind", "object_type" ], "type": "object" }, "EffectDelete": { "properties": { "kind": { "const": "delete", "enum": [ "delete" ], "type": "string" }, "object_type": { "type": "string" } }, "required": [ "kind", "object_type" ], "type": "object" }, "EffectLink": { "properties": { "kind": { "const": "link", "enum": [ "link" ], "type": "string" }, "link_type": { "type": "string" } }, "required": [ "kind", "link_type" ], "type": "object" }, "EffectModify": { "properties": { "kind": { "const": "modify", "enum": [ "modify" ], "type": "string" }, "object_type": { "type": "string" } }, "required": [ "kind", "object_type" ], "type": "object" }, "EffectModifyLink": { "properties": { "kind": { "const": "modify_link", "enum": [ "modify_link" ], "type": "string" }, "link_type": { "type": "string" } }, "required": [ "kind", "link_type" ], "type": "object" }, "EffectSummary": { "description": "Declared side-effect of an action. Mirrors `aerandil_ontology::EffectDecl`: object-targeted effects (create / modify / delete) carry the object type's api_name; link-targeted effects (link / modify_link / unlink) carry the link type's api_name. `unlink` covers both removal and end-dating — the edge stops being live either way. Used by the apply-time validator and by UIs that render an action's expected impact before execution.", "discriminator": { "mapping": { "create": "#/components/schemas/EffectCreate", "delete": "#/components/schemas/EffectDelete", "link": "#/components/schemas/EffectLink", "modify": "#/components/schemas/EffectModify", "modify_link": "#/components/schemas/EffectModifyLink", "unlink": "#/components/schemas/EffectUnlink" }, "propertyName": "kind" }, "oneOf": [ { "$ref": "#/components/schemas/EffectCreate" }, { "$ref": "#/components/schemas/EffectModify" }, { "$ref": "#/components/schemas/EffectDelete" }, { "$ref": "#/components/schemas/EffectLink" }, { "$ref": "#/components/schemas/EffectModifyLink" }, { "$ref": "#/components/schemas/EffectUnlink" } ] }, "EffectUnlink": { "properties": { "kind": { "const": "unlink", "enum": [ "unlink" ], "type": "string" }, "link_type": { "type": "string" } }, "required": [ "kind", "link_type" ], "type": "object" }, "ErasureDecision": { "properties": { "id": { "format": "uuid", "type": "string" }, "links_removed": { "description": "Approve only: number of `links` rows cascade-deleted with the object (in- and out-edges combined). Recorded on the request row for the compliance audit.", "minimum": 0, "type": "integer" }, "status": { "enum": [ "approved", "rejected" ], "type": "string" }, "target_found": { "description": "Approve only: `false` when the target was already absent (a retried approve after a partial failure, or an out-of-band deletion) — the decision is still recorded truthfully with `links_removed = 0`.", "type": "boolean" } }, "required": [ "id", "status" ], "type": "object" }, "ErasureRequest": { "additionalProperties": false, "properties": { "object_id": { "format": "uuid", "type": "string" }, "object_type": { "description": "API name of the object to erase (e.g. `hospitality.person`).", "type": "string" }, "reason": { "description": "Free text naming the data subject or legal basis. Recorded on the request row under the `internal.restricted` marking.", "type": "string" } }, "required": [ "object_type", "object_id" ], "type": "object" }, "ErasureRequestCreated": { "properties": { "id": { "description": "The `hospitality.erasure_request` row id — the durable audit record. Readable via the generic object routes; decided via `.../approve` / `.../reject`.", "format": "uuid", "type": "string" }, "idempotent_replay": { "description": "`true` on a cached `Idempotency-Key` replay.", "type": "boolean" }, "object_id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "status": { "const": "pending" } }, "required": [ "id", "object_type", "object_id", "status" ], "type": "object" }, "ErrorEnvelope": { "additionalProperties": false, "description": "Structured error wrapper. Every non-2xx response from any Aerandil endpoint serialises to this shape; the HTTP status carries the failure class (4xx/5xx), the body adds a stable `code` for programmatic dispatch plus a human-readable `message`.", "properties": { "error": { "properties": { "code": { "description": "Stable, programmatic error code (e.g. `unauthorized`, `forbidden`, `not_found`, `invalid_body`, `invalid_url`, `precondition_failed`, `no_secondary_key`). Clients dispatch on `code`, not on the `message` (which may be localised or contextualised in future versions).", "type": "string" }, "instance_id": { "description": "Request-id correlation handle echoed on the `request-id` response header — support teams correlate without scraping logs.", "type": "string" }, "message": { "description": "Human-readable explanation of the failure.", "type": "string" }, "parameters": { "description": "Per-error structured detail. The shape varies by `code` (e.g. `forbidden_action` carries `{\"action\": \"...\"}`; `precondition_failed` carries `{\"current_version\": N}`)." } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" }, "EventRow": { "description": "One row of the event log — CloudEvents-flavoured shape with top-level `seq` (the BIGSERIAL keyset cursor) plus the flattened ObjectEvent fields. The `kind` discriminator distinguishes object-targeted events (created/updated/ deleted) from link-targeted events (linked/unlinked).", "discriminator": { "mapping": { "object_created": "#/components/schemas/EventRowObjectCreated", "object_deleted": "#/components/schemas/EventRowObjectDeleted", "object_linked": "#/components/schemas/EventRowObjectLinked", "object_unlinked": "#/components/schemas/EventRowObjectUnlinked", "object_updated": "#/components/schemas/EventRowObjectUpdated" }, "propertyName": "kind" }, "oneOf": [ { "$ref": "#/components/schemas/EventRowObjectCreated" }, { "$ref": "#/components/schemas/EventRowObjectUpdated" }, { "$ref": "#/components/schemas/EventRowObjectDeleted" }, { "$ref": "#/components/schemas/EventRowObjectLinked" }, { "$ref": "#/components/schemas/EventRowObjectUnlinked" } ] }, "EventRowObjectCreated": { "properties": { "correlation_id": { "format": "uuid", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "kind": { "const": "object_created", "enum": [ "object_created" ], "type": "string" }, "object_type": { "type": "string" }, "principal": { "$ref": "#/components/schemas/Principal" }, "seq": { "minimum": 0, "type": "integer" }, "ts": { "format": "date-time", "type": "string" } }, "required": [ "seq", "kind", "object_type", "id", "principal", "ts" ], "type": "object" }, "EventRowObjectDeleted": { "properties": { "correlation_id": { "format": "uuid", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "kind": { "const": "object_deleted", "enum": [ "object_deleted" ], "type": "string" }, "object_type": { "type": "string" }, "principal": { "$ref": "#/components/schemas/Principal" }, "seq": { "minimum": 0, "type": "integer" }, "ts": { "format": "date-time", "type": "string" } }, "required": [ "seq", "kind", "object_type", "id", "principal", "ts" ], "type": "object" }, "EventRowObjectLinked": { "properties": { "correlation_id": { "format": "uuid", "type": "string" }, "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "const": "object_linked", "enum": [ "object_linked" ], "type": "string" }, "link_type": { "type": "string" }, "principal": { "$ref": "#/components/schemas/Principal" }, "seq": { "minimum": 0, "type": "integer" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" }, "ts": { "format": "date-time", "type": "string" } }, "required": [ "seq", "kind", "link_type", "from_type", "from_id", "to_type", "to_id", "principal", "ts" ], "type": "object" }, "EventRowObjectUnlinked": { "properties": { "correlation_id": { "format": "uuid", "type": "string" }, "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "const": "object_unlinked", "enum": [ "object_unlinked" ], "type": "string" }, "link_type": { "type": "string" }, "principal": { "$ref": "#/components/schemas/Principal" }, "seq": { "minimum": 0, "type": "integer" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" }, "ts": { "format": "date-time", "type": "string" } }, "required": [ "seq", "kind", "link_type", "from_type", "from_id", "to_type", "to_id", "principal", "ts" ], "type": "object" }, "EventRowObjectUpdated": { "properties": { "correlation_id": { "format": "uuid", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "kind": { "const": "object_updated", "enum": [ "object_updated" ], "type": "string" }, "object_type": { "type": "string" }, "principal": { "$ref": "#/components/schemas/Principal" }, "seq": { "minimum": 0, "type": "integer" }, "ts": { "format": "date-time", "type": "string" } }, "required": [ "seq", "kind", "object_type", "id", "principal", "ts" ], "type": "object" }, "EventStreamFrame": { "description": "One Server-Sent Events frame. Modeled as a JSON object per the OAI text/event-stream registry — `event` is the frame's type, `id` is the frame's id (carries `seq` so reconnects use `Last-Event-ID` for resume), `data` is the JSON payload the consumer parses. The default-name frame carries an EventRow; the `error` frame carries an error envelope.", "discriminator": { "mapping": { "error": "#/components/schemas/EventStreamFrameError", "message": "#/components/schemas/EventStreamFrameMessage" }, "propertyName": "event" }, "oneOf": [ { "$ref": "#/components/schemas/EventStreamFrameMessage" }, { "$ref": "#/components/schemas/EventStreamFrameError" } ] }, "EventStreamFrameError": { "properties": { "data": { "additionalProperties": false, "properties": { "error": { "type": "string" }, "seq": { "description": "Seq of the row that failed to serialise, when known.", "type": "integer" } }, "required": [ "error" ], "type": "object" }, "event": { "const": "error", "enum": [ "error" ], "type": "string" } }, "required": [ "event", "data" ], "type": "object" }, "EventStreamFrameMessage": { "properties": { "data": { "$ref": "#/components/schemas/EventRow" }, "event": { "const": "message", "description": "SSE default event name. On the wire the server omits the `event:` line for these frames; the OAI registry models the default name explicitly so generated SDKs can dispatch.", "enum": [ "message" ], "type": "string" }, "id": { "description": "Stringified `seq` of the carried event row.", "pattern": "^\\d+$", "type": "string" } }, "required": [ "id", "event", "data" ], "type": "object" }, "EventsResponse": { "additionalProperties": false, "properties": { "data": { "items": { "$ref": "#/components/schemas/EventRow" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Opaque cursor for the next page; omitted when the consumer has caught up to the head of the log.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" }, "FeeScheduleResponse": { "properties": { "fee_conversion_bps": { "type": "integer" }, "fee_schedule": { "items": { "$ref": "#/components/schemas/FeeScheduleRow" }, "type": "array" }, "markup_bps": { "description": "The one markup every row carries over Stripe's rate with its fixed fee passed through (\"Stripe + 0.40%\" is 40); null for a schedule set row by row.", "type": [ "integer", "null" ] }, "merchant_account_id": { "format": "uuid", "type": "string" } }, "required": [ "merchant_account_id", "fee_schedule", "fee_conversion_bps" ], "type": "object" }, "FeeScheduleRow": { "additionalProperties": false, "properties": { "bps": { "maximum": 10000, "minimum": 0, "type": "integer" }, "card_present": { "description": "This row prices a terminal's charge rather than an online one.", "type": "boolean" }, "fee_class": { "description": "The card's class: `regional` is the EEA for a UK account and the UK for a eurozone one.", "enum": [ "domestic_standard", "domestic_premium", "regional", "international" ], "type": "string" }, "fixed": { "allOf": [ { "$ref": "#/components/schemas/Money" } ], "description": "The fixed fee the hotel pays — Stripe's own, passed through." }, "processor_bps": { "maximum": 10000, "minimum": 0, "type": "integer" }, "processor_fixed": { "$ref": "#/components/schemas/Money" } }, "required": [ "fee_class", "card_present", "bps", "fixed", "processor_bps", "processor_fixed" ], "type": "object" }, "FraudAssessmentBlockRequest": { "additionalProperties": false, "properties": { "report_to_network": { "default": false, "description": "Give the outcome to Watchtower as the house's confirmed fraud.", "type": "boolean" } }, "type": "object" }, "FraudAssessmentBlockResponse": { "properties": { "assessment_id": { "format": "uuid", "type": "string" }, "payment_id": { "format": "uuid", "type": "string" }, "release": { "enum": [ "released", "queued", "already_released" ], "type": "string" }, "report_note": { "description": "Why a requested report was not sent.", "type": [ "string", "null" ] }, "reported": { "type": "boolean" }, "review_state": { "enum": [ "declined" ], "type": "string" } }, "required": [ "assessment_id", "payment_id", "review_state", "release", "reported" ], "type": "object" }, "FraudAssessmentKeepResponse": { "properties": { "assessment_id": { "format": "uuid", "type": "string" }, "payment_id": { "format": "uuid", "type": "string" }, "review_state": { "enum": [ "approved" ], "type": "string" } }, "required": [ "assessment_id", "payment_id", "review_state" ], "type": "object" }, "FunctionTypeSummary": { "properties": { "api_name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "display_name": { "type": "string" }, "parameter_count": { "minimum": 0, "type": "integer" }, "return_type_kind": { "description": "Kind discriminator of the function's declared return type (e.g. `struct`, `money`, `int`). The full typed schema lives in `/v1/openapi.json` at the per-function `/invoke` path.", "type": "string" }, "target_object_type": { "description": "Bound target object type for targeted functions. Unbound functions leave it null.", "nullable": true, "type": "string" } }, "required": [ "api_name", "display_name", "parameter_count", "return_type_kind" ], "type": "object" }, "HandsetSessionRequest": { "additionalProperties": false, "properties": { "employee_id": { "description": "The employee's HR / payroll identifier — `staff_member`'s business key, what is printed on the badge.", "type": "string" }, "passcode": { "description": "The PIN typed on the handset (6–12 digits).", "type": "string" } }, "required": [ "employee_id", "passcode" ], "type": "object" }, "HandsetSessionResponse": { "allOf": [ { "$ref": "#/components/schemas/TokenResponse" }, { "properties": { "property_id": { "description": "The house the token is bound to — the staff member's home (`staff_works_at_property`), else the house their record is scoped to. Every read, verb and function the token reaches is held to it; another house's answers 403 `property_out_of_scope`.", "format": "uuid", "type": "string" }, "role": { "description": "The floor role the scope vector was derived from.", "enum": [ "housekeeper", "housekeeping_supervisor", "engineer", "runner" ], "type": "string" }, "staff_member_id": { "description": "The `staff_member` the token runs as — also the token's `User` principal id, so \"who am I\" is a plain object read.", "format": "uuid", "type": "string" } }, "required": [ "staff_member_id", "role", "property_id" ], "type": "object" } ] }, "InterfaceImplementerSummary": { "properties": { "object_type": { "type": "string" }, "property_map": { "description": "Interface→local property renames. Absent when every name matches: identity entries are omitted, not echoed back.", "items": { "$ref": "#/components/schemas/InterfacePropertyMapping" }, "type": "array" } }, "required": [ "object_type" ], "type": "object" }, "InterfacePropertyMapping": { "properties": { "interface_property": { "type": "string" }, "local_property": { "type": "string" } }, "required": [ "interface_property", "local_property" ], "type": "object" }, "InterfacePropertySummary": { "properties": { "api_name": { "type": "string" }, "data_type": { "$ref": "#/components/schemas/DataTypeSummary" }, "description": { "type": "string" } }, "required": [ "api_name", "description", "data_type" ], "type": "object" }, "InterfaceTypeSummary": { "properties": { "api_name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "display_name": { "type": "string" }, "implementers": { "items": { "$ref": "#/components/schemas/InterfaceImplementerSummary" }, "type": "array" }, "required_properties": { "description": "Properties every implementer must expose. An enum requirement matches structurally — the vocabulary itself stays per-implementer.", "items": { "$ref": "#/components/schemas/InterfacePropertySummary" }, "type": "array" } }, "required": [ "api_name", "display_name", "required_properties", "implementers" ], "type": "object" }, "IssueInvoiceRequest": { "additionalProperties": false, "properties": { "issued_on": { "description": "The property's business date of issue — the document's date for tax purposes, never the wall clock.", "format": "date", "type": "string" }, "note": { "description": "Printed in the document's footer.", "type": "string" }, "recipient_address_override": { "description": "Print this address instead of the profile's.", "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "type": "object" }, "recipient_kind": { "description": "Defaults to the company when the folio was settled to A/R or the reservation carries one, else the guest.", "enum": [ "person", "company" ], "type": "string" }, "recipient_name_override": { "type": "string" }, "recipient_tax_identifier_override": { "type": "string" } }, "required": [ "issued_on" ], "type": "object" }, "IssueInvoiceResponse": { "properties": { "already_issued": { "description": "True when the folio already carried an uncredited invoice and this call returned it rather than issuing a second one.", "type": "boolean" }, "amount_due": { "$ref": "#/components/schemas/Money" }, "gross_total": { "$ref": "#/components/schemas/Money" }, "invoice_id": { "format": "uuid", "type": "string" }, "issued_on": { "format": "date", "type": "string" }, "kind": { "enum": [ "invoice", "credit_note" ], "type": "string" }, "number": { "description": "e.g. `STAN-2026-000123`.", "type": "string" }, "pdf_stored": { "description": "Whether the rendering reached object storage. False is not an error — the document exists either way, and the pdf route renders on demand.", "type": "boolean" } }, "required": [ "invoice_id", "number", "issued_on", "already_issued", "pdf_stored" ], "type": "object" }, "KeyChargeTapRequest": { "additionalProperties": false, "properties": { "device_id": { "description": "The registered `hospitality.device` to trigger. Must be `active` and carry the Adyen `POIID` in `vendor_device_ref`.", "format": "uuid", "type": "string" } }, "required": [ "device_id" ], "type": "object" }, "KeyEnrollmentReadRequest": { "additionalProperties": false, "properties": { "device_id": { "description": "The registered `hospitality.device` to read on: a `payment_terminal` at the caller's house, `active`, carrying the Adyen `POIID` in `vendor_device_ref`.", "format": "uuid", "type": "string" } }, "required": [ "device_id" ], "type": "object" }, "LinkTypeSummary": { "properties": { "api_name": { "type": "string" }, "cardinality": { "description": "Wire shape follows `format!(\"{:?}\", Cardinality)` then `.to_lowercase()` — single token, no underscores.", "enum": [ "onetoone", "onetomany", "manytoone", "manytomany" ] }, "description": { "nullable": true, "type": "string" }, "from_object_type": { "type": "string" }, "from_role": { "description": "Name of the relationship as seen from the `from` object (e.g. `guest` on a reservation's link to a guest).", "type": "string" }, "to_object_type": { "type": "string" }, "to_role": { "description": "Name of the relationship as seen from the `to` object (e.g. `reservations` on the inverse link from guest).", "type": "string" } }, "required": [ "api_name", "from_object_type", "from_role", "to_object_type", "to_role", "cardinality" ], "type": "object" }, "ListPushSubscriptionsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PushSubscriptionResponse" }, "type": "array" } }, "required": [ "data" ], "type": "object" }, "ListWebhookDeliveriesResponse": { "additionalProperties": false, "properties": { "data": { "items": { "$ref": "#/components/schemas/WebhookDeliveryRecord" }, "type": "array" } }, "required": [ "data" ], "type": "object" }, "ListWebhookSubscriptionsResponse": { "additionalProperties": false, "properties": { "data": { "items": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" }, "type": "array" } }, "required": [ "data" ], "type": "object" }, "MetricReadMeta": { "properties": { "checkpoint_lag_seq": { "description": "The owning projection's consumer lag in event-sequence space at read time.", "type": "integer" }, "computed_at": { "description": "The freshest `computed_at` across the returned rows; `null` for an empty result.", "format": "date-time", "type": [ "string", "null" ] }, "hard_lag_seq": { "description": "Consumer-lag threshold at/over which the read fails `503`.", "type": "integer" }, "hard_staleness_seconds": { "description": "Row-age threshold past which the read fails `503`.", "type": "integer" }, "row_freshness_seconds": { "description": "Wall-clock age in seconds of the freshest returned row; `null` for an empty result.", "type": [ "integer", "null" ] }, "soft_lag_seq": { "description": "Consumer-lag threshold past which the read is soft-stale.", "type": "integer" }, "soft_staleness_seconds": { "description": "Row-age threshold past which the read is soft-stale.", "type": "integer" }, "stale": { "description": "`true` on the soft-stale tier (the answer is served but the rollup has lagged past `soft_lag_seq` or the rows are older than the soft-staleness window). Hard staleness is a `503`, never a `stale: true` `200`.", "type": "boolean" } }, "required": [ "stale", "checkpoint_lag_seq", "soft_staleness_seconds", "hard_staleness_seconds", "soft_lag_seq", "hard_lag_seq" ], "type": "object" }, "MetricReadResponse": { "properties": { "dimensions": { "description": "The categorical group-by axes echoed from the request, in request order. Each appears as a key on every row.", "items": { "type": "string" }, "type": "array" }, "grain": { "description": "The metric's native temporal grain.", "enum": [ "day", "week", "month", "quarter", "year" ], "type": "string" }, "meta": { "$ref": "#/components/schemas/MetricReadMeta" }, "metric": { "description": "The metric name (echoes the path segment).", "type": "string" }, "rows": { "items": { "$ref": "#/components/schemas/MetricReadRow" }, "type": "array" }, "signed": { "description": "Whether negative values are meaningful. A signed metric (forecast bias, today the only family) is read against zero, so quote its direction and not only its magnitude; an unsigned metric floors at zero.", "type": "boolean" }, "unit": { "description": "What `value` is, so a consumer can format it without inferring from the metric name. `percent` is the fraction (0.62, not 62); `native_unit` means the unit follows a dimension value, so the read is only meaningful per that dimension.", "enum": [ "money", "ratio", "percent", "count", "hours", "native_unit" ], "type": "string" }, "version": { "description": "MetricDef version. A formula correction or rollup-shape change ships as a new version, never an in-place mutation — pin against it to detect a semantic shift.", "minimum": 0, "type": "integer" } }, "required": [ "metric", "version", "grain", "unit", "signed", "dimensions", "rows", "meta" ], "type": "object" }, "MetricReadRow": { "additionalProperties": { "description": "One requested dimension's value for this row; `null` for a NULL dimension key.", "type": [ "string", "null" ] }, "description": "One aggregated cell. Each requested dimension is a property keyed by the dimension name with a string (or null) value; `value` is the metric's scalar for that slice.", "properties": { "value": { "description": "The metric's scalar for this slice. `null` when the formula is undefined for the slice (e.g. a 0/0 ratio) — never `NaN` and never a division error.", "type": [ "number", "null" ] } }, "required": [ "value" ], "type": "object" }, "Money": { "additionalProperties": false, "properties": { "amount": { "description": "Exact decimal as a string. Money is never a float — binary floating point cannot hold 0.10.", "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "MoveDeskSessionRequest": { "additionalProperties": false, "properties": { "property_id": { "description": "The house the desk moves to; one the person works at.", "format": "uuid", "type": "string" } }, "required": [ "property_id" ], "type": "object" }, "ObjectTypeDetail": { "allOf": [ { "$ref": "#/components/schemas/ObjectTypeSummary" }, { "properties": { "properties": { "items": { "$ref": "#/components/schemas/PropertySummary" }, "type": "array" } }, "required": [ "properties" ], "type": "object" } ], "description": "`ObjectTypeSummary` extended with the full property list. SDKs can render forms or run client-side validation without parsing the OpenAPI document." }, "ObjectTypeSummary": { "properties": { "api_name": { "type": "string" }, "description": { "nullable": true, "type": "string" }, "display_name": { "type": "string" }, "markings": { "description": "Row-level markings applied to every instance (e.g. `pii`, `payment_data`).", "items": { "type": "string" }, "type": "array" }, "primary_key": { "description": "API name of the property that serves as the type's primary key.", "type": "string" }, "property_count": { "minimum": 0, "type": "integer" }, "scope_levels": { "description": "Levels of the tenancy hierarchy at which instances of this type are allowed to live.", "items": { "enum": [ "tenant", "brand", "portfolio", "property", "venue" ] }, "type": "array" }, "status": { "description": "Lifecycle state of the type definition.", "enum": [ "active", "deprecated" ] }, "title_property": { "description": "API name of the property used for human-readable titles (e.g. an SDK's `.toString()` equivalent).", "nullable": true, "type": "string" } }, "required": [ "api_name", "display_name", "status", "primary_key", "scope_levels", "markings", "property_count" ], "type": "object" }, "OpenDeskSessionRequest": { "additionalProperties": false, "properties": { "outlet_id": { "description": "The outlet whose till the session is (the till's step 2). Named: a till, opened and handed on by the F&B floor's roles (`food_beverage_server`, `food_beverage_manager`); the outlet must trade at the session's property. Absent: the front desk, held by the front office's roles. Neither kind seats the other's roles.", "format": "uuid", "type": "string" }, "property_id": { "description": "The house the shift is at. Optional: unnamed, the shift opens at the signed-in staff record's home (`staff_works_at_property`). A person who works at several houses has a staff record at each, claiming the same identity; naming one of those houses opens the shift there, as that record. A property they have no staff record at is refused.", "format": "uuid", "type": "string" } }, "type": "object" }, "OrgScope": { "description": "Where an object sits in the organisation: the whole tenant, a brand, a portfolio, a property, or a venue within a property. Discriminated by `level`.", "discriminator": { "mapping": { "brand": "#/components/schemas/OrgScopeBrand", "portfolio": "#/components/schemas/OrgScopePortfolio", "property": "#/components/schemas/OrgScopeProperty", "tenant": "#/components/schemas/OrgScopeTenant", "venue": "#/components/schemas/OrgScopeVenue" }, "propertyName": "level" }, "oneOf": [ { "$ref": "#/components/schemas/OrgScopeTenant" }, { "$ref": "#/components/schemas/OrgScopeBrand" }, { "$ref": "#/components/schemas/OrgScopePortfolio" }, { "$ref": "#/components/schemas/OrgScopeProperty" }, { "$ref": "#/components/schemas/OrgScopeVenue" } ] }, "OrgScopeBrand": { "properties": { "brand": { "format": "uuid", "type": "string" }, "level": { "const": "brand", "enum": [ "brand" ], "type": "string" } }, "required": [ "level", "brand" ], "type": "object" }, "OrgScopePortfolio": { "properties": { "level": { "const": "portfolio", "enum": [ "portfolio" ], "type": "string" }, "portfolio": { "format": "uuid", "type": "string" } }, "required": [ "level", "portfolio" ], "type": "object" }, "OrgScopeProperty": { "properties": { "level": { "const": "property", "enum": [ "property" ], "type": "string" }, "property": { "format": "uuid", "type": "string" } }, "required": [ "level", "property" ], "type": "object" }, "OrgScopeTenant": { "properties": { "level": { "const": "tenant", "enum": [ "tenant" ], "type": "string" } }, "required": [ "level" ], "type": "object" }, "OrgScopeVenue": { "properties": { "level": { "const": "venue", "enum": [ "venue" ], "type": "string" }, "property": { "format": "uuid", "type": "string" }, "venue": { "format": "uuid", "type": "string" } }, "required": [ "level", "property", "venue" ], "type": "object" }, "ParticipantDispatchAckEnvelope": { "allOf": [ { "$ref": "#/components/schemas/ParticipantDispatchEnvelope" }, { "properties": { "data": { "properties": { "ack": { "properties": { "envelope_id_received": { "format": "uuid", "type": "string" }, "local_runner_version": { "type": "string" }, "received_at": { "format": "date-time", "type": "string" } }, "required": [ "received_at", "envelope_id_received" ], "type": "object" }, "dispatch_kind": { "minLength": 1, "type": "string" }, "envelope_version": { "const": "1.0", "type": "string" }, "signature": { "$ref": "#/components/schemas/ParticipantDispatchEnvelopeSignatureBlock" } }, "required": [ "envelope_version", "dispatch_kind", "coordinator", "participant", "ack", "idempotency", "signature" ], "type": "object" }, "dataschema": { "const": "https://schema.aerandil.example/0022/dispatch_ack.v1.json" }, "type": { "const": "aerandil.participant_dispatch.acknowledged" } }, "type": "object" } ], "description": "Envelope with `type = aerandil.participant_dispatch.acknowledged` (§7.2). Body of `POST /v1/participant-dispatches/{id}/ack`. The `data` block carries the participant's receipt confirmation; the schema at `dataschema` (`/0022/dispatch_ack.v1.json`) describes its shape." }, "ParticipantDispatchDispatchedEnvelope": { "allOf": [ { "$ref": "#/components/schemas/ParticipantDispatchEnvelope" }, { "properties": { "data": { "additionalProperties": true, "properties": { "coordinator": { "additionalProperties": true, "properties": { "aerandil_coordinator_identity_ref": { "format": "uri-reference", "type": "string" }, "aerandil_correlation_id": { "type": "string" }, "aerandil_run_id": { "minLength": 1, "type": "string" }, "aerandil_tenant_id": { "minLength": 1, "type": "string" } }, "type": "object" }, "dispatch_kind": { "minLength": 1, "type": "string" }, "envelope_version": { "const": "1.0", "type": "string" }, "idempotency": { "additionalProperties": false, "properties": { "dispatch_attempt": { "minimum": 1, "type": "integer" }, "envelope_expires_at": { "format": "date-time", "type": "string" }, "idempotency_key": { "minLength": 1, "type": "string" } }, "required": [ "idempotency_key", "dispatch_attempt", "envelope_expires_at" ], "type": "object" }, "participant": { "additionalProperties": true, "properties": { "aerandil_participation_id": { "minLength": 1, "type": "string" }, "agent_installation_id": { "type": [ "string", "null" ] }, "local_execution_mode": { "enum": [ "operator_runner", "agent_installation", "hosted_connector", "third_party_clean_room", "secure_aggregation" ], "type": "string" }, "participant_object_ref": { "type": [ "string", "null" ] }, "participant_scope": { "enum": [ "tenant", "property", "venue", "channel" ], "type": "string" }, "runner_identity_ref": { "format": "uri-reference", "type": "string" } }, "type": "object" }, "scope": { "additionalProperties": true, "properties": { "aggregation_protocol": { "enum": [ "plain_aggregate_reviewed", "secure_aggregation", "clean_room_query" ], "type": "string" }, "contribution_kinds_admissible": { "items": { "minLength": 1, "type": "string" }, "type": "array" }, "deadline_at": { "format": "date-time", "type": "string" }, "input_window_end": { "format": "date-time", "type": "string" }, "input_window_start": { "format": "date-time", "type": "string" }, "local_code_digest": { "pattern": "^sha256:[0-9a-f]{64}$", "type": "string" }, "minimum_local_runner_version": { "type": "string" }, "payload_size_bytes_max": { "minimum": 1, "type": "integer" }, "recommended_local_runner_version": { "type": "string" }, "scope_schema_version": { "const": "1.0", "type": "string" } }, "type": "object" }, "signature": { "$ref": "#/components/schemas/ParticipantDispatchEnvelopeSignatureBlock" } }, "required": [ "envelope_version", "dispatch_kind", "coordinator", "participant", "idempotency", "signature" ], "type": "object" }, "dataschema": { "description": "Stable schema URI for `data`; normally `/dispatch/{dispatch_kind}.v1.json`.", "format": "uri", "type": "string" }, "type": { "const": "aerandil.participant_dispatch.dispatched" } }, "type": "object" } ], "description": "Envelope with `type = aerandil.participant_dispatch.dispatched` (§7.1). Body of the outbound `webhooks.aerandil_participant_dispatch` request. The `data.dispatch_kind` and `dataschema` URI discriminate the concrete work payload. The v1 dispatcher emits the stable handoff fields below and may add richer `scope` fields as payload assembly grows." }, "ParticipantDispatchEnvelope": { "description": "CloudEvents 1.0 envelope wrapper shared by all five participant-dispatch message types (proposal 0022 §5). The per-data-block schema is referenced by URL in `dataschema`; the on-disk schemas live under `crates/aerandil-schema/spec-schemas/0022/`. SDK consumers match on `type` to dispatch into the typed envelope subclass.", "properties": { "data": { "description": "Aerandil-specific payload (§5.5). Shape varies by `type`; the schema at `dataschema` is the contract.", "type": "object" }, "datacontenttype": { "const": "application/json", "type": "string" }, "dataschema": { "description": "URL of the schema describing `data`. v1 URLs are `https://schema.aerandil.example/0022/...`; receivers match on this to dispatch parsing.", "format": "uri", "type": "string" }, "id": { "description": "UUID v7 per §5.1; reused across retries of the same logical dispatch.", "format": "uuid", "type": "string" }, "source": { "description": "Producer URI; e.g. `aerandil://coordinator/tenant=T-1/program=...` or `aerandil://participant/...`.", "type": "string" }, "specversion": { "const": "1.0", "description": "CloudEvents specversion — pinned at `1.0`.", "type": "string" }, "subject": { "description": "Composite key (e.g. `//`).", "minLength": 1, "type": "string" }, "time": { "description": "RFC 3339; checked against the ±5-minute replay window.", "format": "date-time", "type": "string" }, "type": { "description": "Reverse-DNS message kind.", "enum": [ "aerandil.participant_dispatch.dispatched", "aerandil.participant_dispatch.acknowledged", "aerandil.participant_dispatch.result_submitted", "aerandil.participant_dispatch.delivery_failed", "aerandil.participant_dispatch.quarantine_notice" ], "type": "string" } }, "required": [ "specversion", "id", "source", "type", "subject", "time", "datacontenttype", "dataschema", "data" ], "type": "object" }, "ParticipantDispatchEnvelopeSignatureBlock": { "additionalProperties": false, "description": "Ed25519 detached signature over the canonical bytes of the surrounding envelope (RFC 8785 JCS with the `signature` field elided). Proposal 0022 §8.2.", "properties": { "alg": { "const": "ed25519", "description": "Signature algorithm — v1 supports `ed25519` only.", "type": "string" }, "kid": { "description": "Key identifier. Resolves against `federated_participation.runner_signing_key_ref` for participant-signed envelopes, or the coordinator signing config for coordinator-signed.", "minLength": 1, "type": "string" }, "value": { "description": "Base64 (RFC 4648 §4) detached signature bytes.", "minLength": 1, "type": "string" } }, "required": [ "alg", "kid", "value" ], "type": "object" }, "ParticipantDispatchQuarantineNoticeEnvelope": { "allOf": [ { "$ref": "#/components/schemas/ParticipantDispatchEnvelope" }, { "properties": { "data": { "additionalProperties": false, "properties": { "coordinator": { "additionalProperties": false, "properties": { "aerandil_coordinator_identity_ref": { "format": "uri-reference", "type": "string" }, "aerandil_correlation_id": { "type": "string" }, "aerandil_run_id": { "type": "string" }, "aerandil_tenant_id": { "type": "string" } }, "type": "object" }, "dispatch_kind": { "const": "federated_output_quarantine", "type": "string" }, "envelope_version": { "const": "1.0", "type": "string" }, "participant": { "additionalProperties": false, "properties": { "aerandil_participation_id": { "type": "string" } }, "type": "object" }, "quarantine": { "additionalProperties": false, "properties": { "compliance_scope_only_read_url": { "format": "uri", "type": "string" }, "incident_id": { "minLength": 1, "type": "string" }, "operator_actions_required": { "items": { "minLength": 1, "type": "string" }, "type": "array" }, "output_id": { "minLength": 1, "type": "string" }, "quarantine_reason": { "minLength": 1, "type": "string" } }, "required": [ "output_id", "incident_id", "quarantine_reason", "operator_actions_required" ], "type": "object" }, "signature": { "$ref": "#/components/schemas/ParticipantDispatchEnvelopeSignatureBlock" } }, "required": [ "envelope_version", "dispatch_kind", "coordinator", "participant", "quarantine", "signature" ], "type": "object" }, "dataschema": { "description": "Stable schema URI for `data`; normally `/quarantine_notice.v1.json`.", "format": "uri", "type": "string" }, "type": { "const": "aerandil.participant_dispatch.quarantine_notice" } }, "type": "object" } ], "description": "Envelope with `type = aerandil.participant_dispatch.quarantine_notice` (§7.5). Body of the outbound `webhooks.aerandil_participant_quarantine_notice` request." }, "ParticipantDispatchResultEnvelope": { "allOf": [ { "$ref": "#/components/schemas/ParticipantDispatchEnvelope" }, { "properties": { "data": { "properties": { "dispatch_kind": { "minLength": 1, "type": "string" }, "envelope_version": { "const": "1.0", "type": "string" }, "result": { "properties": { "result_kind": { "minLength": 1, "type": "string" }, "result_status": { "enum": [ "accepted", "rejected_at_local_validator", "abandoned" ], "type": "string" } }, "required": [ "result_kind", "result_status" ], "type": "object" }, "signature": { "$ref": "#/components/schemas/ParticipantDispatchEnvelopeSignatureBlock" } }, "required": [ "envelope_version", "dispatch_kind", "coordinator", "participant", "result", "idempotency", "signature" ], "type": "object" }, "type": { "const": "aerandil.participant_dispatch.result_submitted" } }, "type": "object" } ], "description": "Envelope with `type = aerandil.participant_dispatch.result_submitted` (§7.3). Body of `POST /v1/participant-dispatches/{id}/results`. The `data.result` block is discriminated by `result_kind`; v1 supports `federated_contribution` (per `/0022/result/federated_contribution.v1.json`) and is extensible per dispatch_kind." }, "PortalTokenRequest": { "additionalProperties": false, "description": "Exactly one of `session` or `code`: an access token the caller already holds, or the authorization code from the identity provider's redirect.", "properties": { "code": { "description": "The authorization code from the identity provider's redirect (WorkOS AuthKit, `response_type=code`). The kernel exchanges it with the provider using its own API key — a browser surface never holds a provider token — and verifies the resulting session exactly as `session`.", "type": "string" }, "scope": { "description": "Optional space-separated scope filter. The issued token carries the intersection of this and the human's role-derived scope vector — a portal can request less than the role grants, never more.", "type": "string" }, "session": { "description": "An access token the caller already holds, validated by the cell's configured identity provider (WorkOS).", "type": "string" } }, "type": "object" }, "PortalTokenResponse": { "allOf": [ { "$ref": "#/components/schemas/TokenResponse" }, { "properties": { "principal": { "description": "The `User` principal the token runs as: the `staff_member`'s own id when one claims the signed-in identity, else the stable uuid derived from the identity provider's subject.", "format": "uuid", "type": "string" }, "role": { "description": "The role the scope vector was derived from: the employee's (`front_desk`, `front_office_manager`, `housekeeper`, `housekeeping_supervisor`, `engineer`, `runner`) when a staff record claims the identity, else the organization role (`viewer`, `member`, `admin`).", "type": "string" }, "staff_member_id": { "description": "The `staff_member` the human resolved to — by `identity_subject`, or on a code exchange by the one active employee carrying the provider's verified email (bound on the spot through `update_staff_member_profile`). `null` for an operator with no staff record.", "format": "uuid", "type": [ "string", "null" ] } }, "required": [ "principal", "role" ], "type": "object" } ] }, "Principal": { "description": "The actor that performed an operation. Recorded on every event row (`events.principal` as JSONB). Discriminated by `kind`; the `agent` variant chains back to a delegating principal via `delegated_by`.", "discriminator": { "mapping": { "agent": "#/components/schemas/PrincipalAgent", "service": "#/components/schemas/PrincipalService", "system": "#/components/schemas/PrincipalSystem", "user": "#/components/schemas/PrincipalUser" }, "propertyName": "kind" }, "oneOf": [ { "$ref": "#/components/schemas/PrincipalSystem" }, { "$ref": "#/components/schemas/PrincipalUser" }, { "$ref": "#/components/schemas/PrincipalService" }, { "$ref": "#/components/schemas/PrincipalAgent" } ] }, "PrincipalAgent": { "properties": { "delegated_by": { "$ref": "#/components/schemas/Principal", "description": "The principal on whose behalf the agent acted." }, "kind": { "const": "agent", "enum": [ "agent" ], "type": "string" }, "model": { "description": "Model the agent ran with (e.g. `claude-opus-4-7`).", "type": "string" }, "vendor": { "description": "Issuer of the agent (e.g. `anthropic`, `openai`).", "type": "string" }, "version": { "description": "Version string under the vendor's namespace.", "type": "string" } }, "required": [ "kind", "vendor", "version", "model" ], "type": "object" }, "PrincipalService": { "properties": { "kind": { "const": "service", "enum": [ "service" ], "type": "string" }, "name": { "description": "Service api_name (e.g. `connector.opera_pms`).", "type": "string" } }, "required": [ "kind", "name" ], "type": "object" }, "PrincipalSystem": { "properties": { "kind": { "const": "system", "enum": [ "system" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, "PrincipalUser": { "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "const": "user", "enum": [ "user" ], "type": "string" } }, "required": [ "kind", "id" ], "type": "object" }, "PrintJob": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "device_id": { "format": "uuid", "type": "string" }, "drawer": { "type": "boolean" }, "idempotent_replay": { "type": "boolean" }, "job_id": { "format": "int64", "type": "integer" }, "receipt_id": { "format": "uuid", "type": "string" }, "status": { "enum": [ "queued", "printing", "printed", "failed" ], "type": "string" } }, "required": [ "job_id", "status", "device_id", "receipt_id", "drawer", "created_at" ], "type": "object" }, "PrintReceiptRequest": { "additionalProperties": false, "properties": { "device_id": { "description": "The printer (`hospitality.device`, `kind = printer`).", "format": "uuid", "type": "string" }, "drawer": { "default": false, "description": "Kick the cash drawer — a receipt that took cash, within ten minutes of its issue.", "type": "boolean" } }, "required": [ "device_id" ], "type": "object" }, "PropertySummary": { "additionalProperties": false, "properties": { "api_name": { "type": "string" }, "data_type": { "$ref": "#/components/schemas/DataTypeSummary" }, "description": { "nullable": true, "type": "string" }, "display_name": { "type": "string" }, "indexed": { "type": "boolean" }, "markings": { "description": "Marking api_names (e.g. `pii`, `payment_data`) that gate row-level access. Empty when no markings apply.", "items": { "type": "string" }, "type": "array" }, "required": { "type": "boolean" } }, "required": [ "api_name", "display_name", "data_type", "required", "indexed", "markings" ], "type": "object" }, "ProvenanceEnvelope": { "description": "Per-property source attribution and pins. An entry under `properties` means the property's current value came from that source (on the source's own clock, `source_updated_at`); an entry under `pins` is a human override protecting the property from sourced writes.", "properties": { "pins": { "additionalProperties": { "properties": { "pinned_at": { "format": "date-time", "type": "string" }, "pinned_by": { "type": "object" }, "reason": { "type": "string" } }, "required": [ "reason" ], "type": "object" }, "type": "object" }, "properties": { "additionalProperties": { "properties": { "external_id": { "type": "string" }, "recorded_at": { "format": "date-time", "type": "string" }, "source": { "type": "string" }, "source_updated_at": { "format": "date-time", "type": "string" }, "stream": { "type": "string" } }, "required": [ "source", "recorded_at" ], "type": "object" }, "type": "object" } }, "type": "object" }, "PushApplicationServerKeyResponse": { "properties": { "application_server_key": { "description": "The deployment's VAPID public key (65-byte uncompressed P-256 point, base64url). Decode it and pass it as `applicationServerKey` to `pushManager.subscribe()`.", "type": "string" } }, "required": [ "application_server_key" ], "type": "object" }, "PushSubscriptionRequest": { "additionalProperties": false, "description": "A browser's Web Push subscription (`platform` `web`, the default: endpoint, keys and app_url), or the Ithaca store app's device token (`platform` `apns` / `fcm`: token only). A native platform the deployment does not send to is `404 push_not_configured`.", "properties": { "app_url": { "description": "`web`: the handset's origin, e.g. `https://ithaca.example/`; the sender composes the notification's `navigate` target from it.", "format": "uri", "type": "string" }, "declarative": { "default": false, "description": "Subscribed through `window.pushManager` (Declarative Web Push, Safari 18.4+); such messages are sent as `application/notification+json`.", "type": "boolean" }, "endpoint": { "description": "`web`: the push resource URL (RFC 8030).", "format": "uri", "type": "string" }, "expiration_time": { "description": "Echoed by browsers; ignored." }, "keys": { "additionalProperties": false, "description": "`web`: the user agent's RFC 8291 key material.", "properties": { "auth": { "description": "The 16-byte authentication secret, base64url.", "type": "string" }, "p256dh": { "description": "The user agent's P-256 public key, base64url (65-byte uncompressed point).", "type": "string" } }, "required": [ "p256dh", "auth" ], "type": "object" }, "platform": { "default": "web", "description": "Where the push goes: a browser's push service, Apple (iOS app) or Firebase Cloud Messaging (Android app).", "enum": [ "web", "apns", "fcm" ], "type": "string" }, "token": { "description": "`apns`: the APNs device token (hex). `fcm`: the FCM registration token.", "type": "string" }, "user_agent": { "maxLength": 512, "type": "string" } }, "type": "object" }, "PushSubscriptionResponse": { "properties": { "app_url": { "description": "`web` only.", "format": "uri", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "declarative": { "type": "boolean" }, "endpoint": { "description": "The push resource URL (`web`) or the device token (`apns` / `fcm`).", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "idempotent_replay": { "description": "Present and `true` when the response was replayed for a repeated `Idempotency-Key`.", "type": "boolean" }, "last_delivered_at": { "format": "date-time", "type": "string" }, "platform": { "enum": [ "web", "apns", "fcm" ], "type": "string" }, "staff_member_id": { "description": "The staff member the endpoint currently delivers to.", "format": "uuid", "type": "string" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "user_agent": { "type": "string" } }, "required": [ "id", "tenant_id", "staff_member_id", "platform", "endpoint", "declarative", "created_at", "updated_at" ], "type": "object" }, "RetireCardResponse": { "properties": { "card_status": { "enum": [ "removed" ], "type": "string" }, "payment_card_id": { "format": "uuid", "type": "string" } }, "required": [ "payment_card_id", "card_status" ], "type": "object" }, "SetHandsetPasscodeRequest": { "additionalProperties": false, "properties": { "passcode": { "description": "6–12 ASCII digits. Absent or null clears the PIN — the employee can no longer sign in on a handset.", "pattern": "^[0-9]{6,12}$", "type": [ "string", "null" ] } }, "type": "object" }, "SetTenantWriteModeRequest": { "additionalProperties": false, "description": "Set a tenant's write-mode, with an optional operator note.", "properties": { "mode": { "description": "`read_only` quiesces the tenant (writes refused with 503 + Retry-After; reads live) — the transient cutover freeze; `relocated` marks this cell as no longer the owner after a relocation cuts over (writes refused with **421 Misdirected Request**; reads live) — the §5 ownership flip, terminal at this cell; `active` lifts either state.", "enum": [ "active", "read_only", "relocated" ], "type": "string" }, "reason": { "description": "Operator note recorded for audit (e.g. the relocation job id).", "type": [ "string", "null" ] } }, "required": [ "mode" ], "type": "object" }, "SetupIntentRequest": { "additionalProperties": false, "properties": { "person_id": { "description": "The guest whose card is being collected. Their existing cards at this merchant name the processor customer to reuse; the first card mints one.", "format": "uuid", "type": "string" }, "property_id": { "description": "The house collecting the card — the merchant its stored-credential agreement names, whose Stripe Customer the card joins and the only one that may draw on it. A desk session's own house whatever is sent; every other bearer names one (`property_required` otherwise).", "format": "uuid", "type": "string" } }, "required": [ "person_id" ], "type": "object" }, "SetupIntentResponse": { "properties": { "client_secret": { "description": "The half that goes to the browser, where Stripe.js completes the collection with the publishable key. Scoped to this one intent and useless for anything else, which is why it can be handed out at all.", "type": "string" }, "setup_intent_id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "setup_intent_id", "client_secret", "status" ], "type": "object" }, "StoreCardRequest": { "additionalProperties": false, "properties": { "capture_kind": { "description": "How the card reached the processor. The desk knows this and the processor does not, and the difference decides interchange, chargeback liability, and whether SCA was satisfied.", "enum": [ "terminal", "keyed_by_staff", "guest_device", "imported" ], "type": "string" }, "reservation_id": { "description": "The booking this card also guarantees, when it does.", "format": "uuid", "type": "string" }, "retain_until": { "description": "Storage-limitation clock. The desk's jurisdiction decides it.", "format": "date", "type": "string" }, "setup_intent_id": { "description": "The SetupIntent the browser just completed. Not the card's details — those are read back from the processor.", "type": "string" } }, "required": [ "setup_intent_id", "capture_kind", "retain_until" ], "type": "object" }, "StoreCardResponse": { "properties": { "brand": { "enum": [ "visa", "mastercard", "amex", "discover", "diners", "jcb", "unionpay", "cartes_bancaires", "eftpos_au", "interac", "maestro", "unknown" ], "type": "string" }, "expiry_month": { "maximum": 12, "minimum": 1, "type": "integer" }, "expiry_year": { "type": "integer" }, "last4": { "description": "For a wallet card this is the device account number's last four, not the funding card's — the desk must say so rather than read it out as the guest's card.", "type": "string" }, "payment_card_id": { "format": "uuid", "type": "string" }, "wallet": { "enum": [ "apple_pay", "google_pay", "samsung_pay", "link", "click_to_pay", "other", null ], "type": [ "string", "null" ] } }, "required": [ "payment_card_id", "brand", "last4", "expiry_month", "expiry_year" ], "type": "object" }, "StoreVirtualCardRequest": { "additionalProperties": false, "properties": { "activation_date": { "description": "The first day the channel lets the house charge the card (the house's calendar); the activation charge sweeps it from the house's midnight on it.", "format": "date", "type": "string" }, "funded_amount": { "$ref": "#/components/schemas/Money" }, "retain_until": { "description": "Storage-limitation clock.", "format": "date", "type": "string" }, "setup_intent_id": { "description": "The SetupIntent from `POST /v1/reservations/{reservation_id}/virtual-card-setup-intents` the desk completed with the channel's card.", "type": "string" } }, "required": [ "setup_intent_id", "retain_until" ], "type": "object" }, "StripePublishableKeyResponse": { "properties": { "publishable_key": { "description": "The publishable half. Safe in a browser; it can create and confirm intents but cannot read or move money.", "type": "string" } }, "required": [ "publishable_key" ], "type": "object" }, "StructFieldSummary": { "additionalProperties": false, "properties": { "data_type": { "$ref": "#/components/schemas/DataTypeSummary" }, "name": { "type": "string" }, "required": { "type": "boolean" } }, "required": [ "name", "data_type", "required" ], "type": "object" }, "TableDigest": { "description": "One table's fingerprint: a row count plus a 64-hex SHA-256-XOR checksum over the table's portable columns (all-zero hex when the table is empty for the tenant). The XOR fold is order- and collation-independent, so two cells need not return rows in the same order to compare equal.", "properties": { "checksum": { "description": "64-hex content checksum; all-zero when the table is empty.", "type": "string" }, "count": { "description": "Row count for the tenant in this table.", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "count", "checksum" ], "type": "object" }, "TenantErasureRequest": { "additionalProperties": false, "properties": { "tenant_id": { "description": "Tenant to decommission. The caller is an Aerandil operator administering this tenant; the handler does not require the caller's principal to live inside `tenant_id` (that would defeat the off-tenant operator semantic).", "format": "uuid", "type": "string" } }, "required": [ "tenant_id" ], "type": "object" }, "TenantErasureResponse": { "properties": { "idempotent_replay": { "type": "boolean" }, "links_removed": { "minimum": 0, "type": "integer" }, "objects_removed": { "minimum": 0, "type": "integer" }, "status": { "const": "erased" }, "tenant_id": { "format": "uuid", "type": "string" } }, "required": [ "tenant_id", "objects_removed", "links_removed", "status" ], "type": "object" }, "TenantExportLine": { "description": "One line of the NDJSON tenant export stream. `kind` discriminates between table rows (object / link / event) and the terminal `error` line emitted on mid-stream failure.", "discriminator": { "mapping": { "error": "#/components/schemas/TenantExportLineError", "event": "#/components/schemas/TenantExportLineEvent", "link": "#/components/schemas/TenantExportLineLink", "object": "#/components/schemas/TenantExportLineObject" }, "propertyName": "kind" }, "oneOf": [ { "$ref": "#/components/schemas/TenantExportLineObject" }, { "$ref": "#/components/schemas/TenantExportLineLink" }, { "$ref": "#/components/schemas/TenantExportLineEvent" }, { "$ref": "#/components/schemas/TenantExportLineError" } ] }, "TenantExportLineError": { "additionalProperties": false, "properties": { "kind": { "const": "error", "enum": [ "error" ], "type": "string" }, "message": { "description": "Stream-level failure surfaced in-band. Emitted as the last line when the dump errors after headers have been sent — the receiver tails the body and observes the error rather than getting a non-200 status.", "type": "string" } }, "required": [ "kind", "message" ], "type": "object" }, "TenantExportLineEvent": { "properties": { "correlation_id": { "format": "uuid", "nullable": true, "type": "string" }, "event_kind": { "description": "Underlying `ObjectEvent` discriminant — `object_created`, `object_updated`, `object_deleted`, `object_linked`, `object_unlinked`. (Distinct from the top-level `kind` which is always `event` for this variant.)", "type": "string" }, "kind": { "const": "event", "enum": [ "event" ], "type": "string" }, "occurred_at": { "format": "date-time", "type": "string" }, "payload": { "type": "object" }, "principal": { "$ref": "#/components/schemas/Principal" }, "seq": { "description": "The source DB's global surrogate ordinal — a within-stream resume cursor only. A relocation import reassigns it; use `tenant_seq` for portable ordering.", "minimum": 0, "type": "integer" }, "tenant_id": { "format": "uuid", "type": "string" }, "tenant_seq": { "description": "Portable per-tenant ordinal (`UNIQUE (tenant_id, tenant_seq)`, migration 0019) that travels with the tenant across a cross-cell relocation. Always present for exported (tenant-owned) rows. (The source-local `commit_xid` CDC horizon is deliberately not exported — a destination re-stamps its own.)", "minimum": 1, "nullable": true, "type": "integer" } }, "required": [ "kind", "seq", "occurred_at", "event_kind", "payload", "principal", "tenant_id" ], "type": "object" }, "TenantExportLineLink": { "properties": { "effective_from": { "description": "When the link starts being in effect (migration 0011).", "format": "date-time", "type": "string" }, "effective_to": { "description": "When the link stops being in effect; null is open-ended (still in effect).", "format": "date-time", "nullable": true, "type": "string" }, "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "const": "link", "enum": [ "link" ], "type": "string" }, "link_type": { "type": "string" }, "properties": { "description": "Typed link-property bag (migration 0012); `{}` for adjacency-only links.", "type": "object" }, "tenant_id": { "format": "uuid", "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "kind", "link_type", "from_type", "from_id", "to_type", "to_id", "tenant_id", "effective_from", "properties" ], "type": "object" }, "TenantExportLineObject": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "deleted_at": { "format": "date-time", "nullable": true, "type": "string" }, "deleted_by": { "nullable": true }, "id": { "format": "uuid", "type": "string" }, "kind": { "const": "object", "enum": [ "object" ], "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "description": "Org-scope envelope (tenant/brand/portfolio/property/venue)." }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 0, "type": "integer" } }, "required": [ "kind", "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "TenantExportRequest": { "additionalProperties": false, "properties": { "tenant_id": { "format": "uuid", "type": "string" } }, "required": [ "tenant_id" ], "type": "object" }, "TenantImportLoadCount": { "properties": { "loaded": { "description": "Rows newly inserted by this import.", "minimum": 0, "type": "integer" }, "skipped": { "description": "Rows already present, skipped idempotently (not an error).", "minimum": 0, "type": "integer" } }, "required": [ "loaded", "skipped" ], "type": "object" }, "TenantImportSummary": { "description": "What a tenant import committed: a per-table tally of rows newly loaded vs. skipped (already present under the idempotent ON CONFLICT DO NOTHING).", "properties": { "events": { "$ref": "#/components/schemas/TenantImportLoadCount" }, "links": { "$ref": "#/components/schemas/TenantImportLoadCount" }, "objects": { "$ref": "#/components/schemas/TenantImportLoadCount" }, "tenant_id": { "format": "uuid", "type": "string" } }, "required": [ "tenant_id", "objects", "links", "events" ], "type": "object" }, "TenantVerifyDigest": { "description": "An independent content fingerprint of a tenant's footprint for the relocation cutover verify gate (0007 §4 step 5). Two cells whose digests compare equal hold identical portable content for the tenant.", "properties": { "events": { "$ref": "#/components/schemas/TableDigest" }, "links": { "$ref": "#/components/schemas/TableDigest" }, "objects": { "$ref": "#/components/schemas/TableDigest" }, "tenant_id": { "format": "uuid", "type": "string" } }, "required": [ "tenant_id", "objects", "links", "events" ], "type": "object" }, "TenantWriteModeRecord": { "description": "A tenant's write-mode plus the provenance of the last change. A tenant that was never set reads back `active` with null provenance.", "properties": { "mode": { "enum": [ "active", "read_only", "relocated" ], "type": "string" }, "reason": { "description": "Operator note from the last set, if any.", "type": [ "string", "null" ] }, "set_by": { "additionalProperties": true, "description": "The principal that last set the mode (serialised).", "type": [ "object", "null" ] }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "description": "When the mode was last set; null for a synthesised default.", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "tenant_id", "mode" ], "type": "object" }, "TokenRequest": { "additionalProperties": false, "description": "OAuth 2.1 client_credentials grant body. JSON-encoded, not form-urlencoded — see `/oauth/token`'s endpoint description for the rationale.", "properties": { "client_id": { "type": "string" }, "client_secret": { "description": "Verified against the client's argon2id-hashed secret.", "type": "string" }, "grant_type": { "const": "client_credentials", "description": "Aerandil supports only `client_credentials` in v1. Any other value yields `422 unsupported_grant_type`." }, "scope": { "description": "Optional space-separated scope filter. When present, the issued token's scope is the intersection of the filter and the client's pre-provisioned scopes — a way to narrow per-request without rotating the client's permanent grant.", "type": "string" } }, "required": [ "grant_type", "client_id", "client_secret" ], "type": "object" }, "TokenResponse": { "properties": { "access_token": { "description": "Short-lived HS256 JWT. Send as `Authorization: Bearer ` on subsequent calls.", "type": "string" }, "expires_in": { "description": "Token lifetime in seconds. Default 3600 (one hour); deployment-configurable via `AERANDIL_TOKEN_TTL_SECS`.", "minimum": 1, "type": "integer" }, "scope": { "description": "Space-separated list of granted scopes. The set the token actually carries — already narrowed by any `scope` request filter and the client's pre-provisioned grants.", "type": "string" }, "token_type": { "const": "Bearer", "description": "Always `Bearer` in v1." } }, "required": [ "access_token", "token_type", "expires_in", "scope" ], "type": "object" }, "UpdateWebhookSubscriptionRequest": { "additionalProperties": false, "description": "All fields optional — only the supplied ones change. Setting `status` to `active` is the reset path for a `dead_letter` subscription.", "properties": { "filter": { "$ref": "#/components/schemas/WebhookSubscriptionFilter" }, "status": { "$ref": "#/components/schemas/WebhookSubscriptionStatus" }, "url": { "format": "uri", "type": "string" } }, "type": "object" }, "WatchtowerContest": { "description": "An answer a house contested, the house it was given to, and the contributions behind it.", "properties": { "band_floor": { "enum": [ "low", "medium", "high", "block", "not_assessed", null ], "type": [ "string", "null" ] }, "contest_reason": { "type": [ "string", "null" ] }, "contested_at": { "format": "date-time", "type": "string" }, "contributions": { "items": { "$ref": "#/components/schemas/WatchtowerContribution" }, "type": "array" }, "contributor_breadth": { "enum": [ "none", "below_cohort", "cohort_met", null ], "type": [ "string", "null" ] }, "floor_basis": { "enum": [ "none", "contact", "card_unconfirmed", "card_corroborated", "card_own_house", "desk_override", null ], "type": [ "string", "null" ] }, "issued_at": { "format": "date-time", "type": "string" }, "kinds_queried": { "items": { "enum": [ "card", "email", "phone" ], "type": "string" }, "type": "array" }, "match_count_bucket": { "enum": [ "none", "one", "few", "many", null ], "type": [ "string", "null" ] }, "matched_kinds": { "items": { "enum": [ "card", "email", "phone" ], "type": "string" }, "type": "array" }, "property_code": { "type": [ "string", "null" ] }, "property_id": { "format": "uuid", "type": [ "string", "null" ] }, "property_name": { "type": [ "string", "null" ] }, "recency_bucket": { "enum": [ "none", "within_30_days", "within_180_days", "older", null ], "type": [ "string", "null" ] }, "reference": { "type": [ "string", "null" ] }, "salt_epoch": { "type": "integer" }, "signal_id": { "format": "uuid", "type": "string" }, "subject_id": { "type": [ "string", "null" ] }, "subject_kind": { "type": [ "string", "null" ] }, "tenant_id": { "format": "uuid", "type": "string" }, "traceable": { "description": "Whether the answer kept its digests (since 2026-11-03).", "type": "boolean" } }, "required": [ "signal_id", "tenant_id", "kinds_queried", "matched_kinds", "salt_epoch", "issued_at", "contested_at", "traceable", "contributions" ], "type": "object" }, "WatchtowerContestList": { "properties": { "contests": { "items": { "$ref": "#/components/schemas/WatchtowerContest" }, "type": "array" }, "limit": { "type": "integer" } }, "required": [ "limit", "contests" ], "type": "object" }, "WatchtowerContribution": { "description": "A contribution behind a contested answer, as the platform's review reads it: whose, what, and whether it still counts.", "properties": { "after_answer": { "description": "Contributed after the answer was given, so it did not shape it.", "type": "boolean" }, "contributed_at": { "format": "date-time", "type": "string" }, "contribution_id": { "format": "uuid", "type": "string" }, "counts": { "description": "Whether the next answer counts it: active, its house still consenting.", "type": "boolean" }, "matched_kinds": { "items": { "enum": [ "card", "email", "phone" ], "type": "string" }, "type": "array" }, "outcome": { "enum": [ "chargeback_lost_fraud", "confirmed_fraud" ], "type": "string" }, "own_house": { "description": "The contesting house's own contribution.", "type": "boolean" }, "property_code": { "type": [ "string", "null" ] }, "property_id": { "format": "uuid", "type": [ "string", "null" ] }, "property_name": { "type": [ "string", "null" ] }, "reference": { "type": [ "string", "null" ] }, "source_reference": { "description": "The processor's dispute id, or the assessment id.", "type": [ "string", "null" ] }, "status": { "enum": [ "active", "withdrawn" ], "type": "string" }, "tenant_id": { "format": "uuid", "type": "string" }, "withdrawal_reason": { "type": [ "string", "null" ] }, "withdrawn_at": { "format": "date-time", "type": [ "string", "null" ] }, "withdrawn_by": { "enum": [ "house", "platform", null ], "type": [ "string", "null" ] } }, "required": [ "contribution_id", "tenant_id", "own_house", "matched_kinds", "outcome", "status", "counts", "contributed_at", "after_answer" ], "type": "object" }, "WatchtowerWithdrawRequest": { "additionalProperties": false, "properties": { "reason": { "description": "Why the platform takes it back — what the review found.", "minLength": 1, "type": "string" } }, "required": [ "reason" ], "type": "object" }, "WatchtowerWithdrawResponse": { "properties": { "contribution_id": { "format": "uuid", "type": "string" }, "property_id": { "format": "uuid", "type": [ "string", "null" ] }, "status": { "enum": [ "withdrawn" ], "type": "string" }, "tenant_id": { "format": "uuid", "type": "string" }, "withdrawal_reason": { "type": [ "string", "null" ] }, "withdrawn_at": { "format": "date-time", "type": [ "string", "null" ] }, "withdrawn_by": { "enum": [ "platform" ], "type": "string" } }, "required": [ "contribution_id", "tenant_id", "status", "withdrawn_by" ], "type": "object" }, "WebhookDeliveryBatch": { "additionalProperties": false, "description": "Outbound delivery batch — the request body Aerandil POSTs to every active subscription's receiver URL. CloudEvents 1.0 envelope carrying a non-empty `events` array.", "properties": { "delivered_at": { "format": "date-time", "type": "string" }, "delivery_id": { "description": "Fresh per attempt — not stable across retries (use the per-event `id` for at-least-once de-duplication).", "format": "uuid", "type": "string" }, "events": { "items": { "$ref": "#/components/schemas/WebhookDeliveryEvent" }, "minItems": 1, "type": "array" }, "specversion": { "const": "1.0", "description": "CloudEvents spec version." } }, "required": [ "specversion", "delivery_id", "delivered_at", "events" ], "type": "object" }, "WebhookDeliveryEvent": { "additionalProperties": false, "description": "One CloudEvents-shaped entry inside a delivery batch. The `data` field carries the underlying `ObjectEvent` — same shape returned by `GET /v1/events` (minus the top-level `seq`, which lives in `id` here per CloudEvents conventions). Receivers de-duplicate by `id`.", "properties": { "data": { "description": "The underlying `ObjectEvent` — same discriminated `kind` shape as `EventRow`, minus the top-level `seq` (which is carried in `id` here).", "type": "object" }, "datacontenttype": { "const": "application/json" }, "id": { "description": "Stringified `seq` of the underlying event log row. Use this for at-least-once de-duplication on the receiver side.", "pattern": "^\\d+$", "type": "string" }, "principal": { "$ref": "#/components/schemas/Principal" }, "source": { "const": "aerandil", "description": "Static — the producer is always Aerandil." }, "specversion": { "const": "1.0" }, "time": { "format": "date-time", "type": "string" }, "type": { "description": "`aerandil.` — one of `aerandil.object.created`, `aerandil.object.updated`, `aerandil.object.deleted`, `aerandil.link.created`, `aerandil.link.deleted`.", "enum": [ "aerandil.object.created", "aerandil.object.updated", "aerandil.object.deleted", "aerandil.link.created", "aerandil.link.deleted" ], "type": "string" } }, "required": [ "specversion", "type", "source", "id", "time", "datacontenttype", "principal", "data" ], "type": "object" }, "WebhookDeliveryRecord": { "description": "One row in `webhook_deliveries` — append-only audit per attempt. The wire-level evidence operators need to debug a misbehaving receiver.", "properties": { "attempt": { "description": "1-based attempt counter.", "minimum": 1, "type": "integer" }, "attempted_at": { "format": "date-time", "type": "string" }, "completed_at": { "description": "When the attempt finished — success, failure, or timeout. Unset only if a worker crashed mid-flight.", "format": "date-time", "type": "string" }, "error": { "description": "Transport-level error message when the receiver did not answer (connection refused, TLS handshake failure, timeout, etc.).", "type": "string" }, "from_seq": { "description": "Inclusive lower bound of the seq range covered by this attempt.", "minimum": 0, "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "response_excerpt": { "description": "First 512 bytes of the receiver's response body.", "maxLength": 512, "type": "string" }, "status": { "$ref": "#/components/schemas/WebhookDeliveryStatus" }, "status_code": { "description": "HTTP status the receiver returned. Unset on transport errors (receiver never responded).", "type": "integer" }, "subscription_id": { "format": "uuid", "type": "string" }, "to_seq": { "description": "Inclusive upper bound. A success advances the subscription cursor to `to_seq`; a failure leaves it where it was.", "minimum": 0, "type": "integer" } }, "required": [ "id", "subscription_id", "from_seq", "to_seq", "attempt", "status", "attempted_at" ], "type": "object" }, "WebhookDeliveryStatus": { "description": "Per-attempt delivery outcome. Distinct from `WebhookSubscriptionStatus`: a single delivery row can be `failed` while the parent subscription stays `active` (within retry budget).", "enum": [ "success", "failed", "dead_letter" ] }, "WebhookSubscriptionFilter": { "additionalProperties": false, "description": "Filter narrowing what the worker delivers. Empty / absent means \"every event in the tenant\".", "properties": { "object_types": { "description": "Narrow to events whose `object_type` matches one of the listed api_names. For link events, either endpoint type matching counts — a filter of `[\"hospitality.reservation\"]` includes `reservation_for_guest` events.", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "WebhookSubscriptionResponse": { "description": "Subscription state without the signing key. The `*_key_fingerprint` fields are the first 8 hex chars of `sha256(key)` — enough to confirm a rotation worked without exposing the secret.", "properties": { "consecutive_failures": { "description": "Resets to 0 on the first 2xx after any failure. Transitioning to `dead_letter` happens at 12 consecutive failures (~3-day retry window).", "minimum": 0, "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "filter": { "$ref": "#/components/schemas/WebhookSubscriptionFilter" }, "id": { "format": "uuid", "type": "string" }, "last_delivered_seq": { "description": "Cursor into the event log. Advances to the highest `seq` *read* on every successful delivery — filtered-out events are still cursored past so the worker stays bounded under a narrow filter.", "minimum": 0, "type": "integer" }, "next_attempt_at": { "description": "Earliest moment the worker will retry. Unset when the subscription is caught up; set in the future when an exponential-backoff retry is scheduled.", "format": "date-time", "type": "string" }, "primary_key_fingerprint": { "description": "First 8 hex chars of `sha256(primary_signing_key)` — 16 chars in total. Exposed instead of the secret on every read.", "pattern": "^[0-9a-f]{16}$", "type": "string" }, "secondary_key_fingerprint": { "description": "Present during a key-rotation window. Cleared on promote-key.", "pattern": "^[0-9a-f]{16}$", "type": "string" }, "status": { "$ref": "#/components/schemas/WebhookSubscriptionStatus" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "url": { "description": "Receiver URL. HTTPS-only (except loopback in dev).", "format": "uri", "type": "string" } }, "required": [ "id", "tenant_id", "url", "filter", "last_delivered_seq", "status", "consecutive_failures", "created_at", "updated_at", "primary_key_fingerprint" ], "type": "object" }, "WebhookSubscriptionStatus": { "description": "Lifecycle of a webhook subscription. `dead_letter` is sticky — the worker stops attempting further deliveries until the customer PATCHes status back to `active` (and typically advances `last_delivered_seq` past the poison batch).", "enum": [ "active", "paused", "dead_letter" ] }, "WebhookSubscriptionWithKeyResponse": { "allOf": [ { "$ref": "#/components/schemas/WebhookSubscriptionResponse" }, { "properties": { "idempotent_replay": { "description": "Set to `true` on a retry that the idempotency helper served from cache. Treat as advisory — the response body is the canonical state regardless.", "type": "boolean" }, "signing_key": { "description": "32-byte HMAC key, hex-encoded (64 chars). Used to verify the `Aerandil-Signature` header on every inbound delivery to the receiver.", "pattern": "^[0-9a-f]{64}$", "type": "string" }, "signing_key_slot": { "description": "`primary` on create (the only key); `secondary` on rotate (added alongside the existing primary during the rotation window).", "enum": [ "primary", "secondary" ] } }, "required": [ "signing_key", "signing_key_slot" ], "type": "object" } ], "description": "Subscription state plus the freshly minted signing key. Returned ONLY by create (`POST .../webhook-subscriptions`) and rotate (`POST .../{id}/rotate-key`); every other read surfaces fingerprints only. Customer captures the secret into their vault at this moment — there is no recovery path if it's lost (the rotation flow is the recovery)." } }, "securitySchemes": { "aerandil_oauth": { "description": "OAuth 2.1 client_credentials flow against `/oauth/token`. Either the `actions:apply` catch-all OR a specific `actions:{api_name}:apply` grant authorises an action call — neither subsumes the other.", "flows": { "clientCredentials": { "scopes": { "actions:apply": "Catch-all apply scope for every registered action. Issue per-action scopes (`actions:{api_name}:apply`) instead when granting narrowly to a service account.", "actions:hospitality.action.accept_waitlist_entry:apply": "Apply `hospitality.action.accept_waitlist_entry`.", "actions:hospitality.action.acknowledge_channel_reservation:apply": "Apply `hospitality.action.acknowledge_channel_reservation`.", "actions:hospitality.action.activate_automation:apply": "Apply `hospitality.action.activate_automation`.", "actions:hospitality.action.add_banquet_order_line:apply": "Apply `hospitality.action.add_banquet_order_line`.", "actions:hospitality.action.add_check_line:apply": "Apply `hospitality.action.add_check_line`.", "actions:hospitality.action.add_check_payment:apply": "Apply `hospitality.action.add_check_payment`.", "actions:hospitality.action.add_dependent_membership:apply": "Apply `hospitality.action.add_dependent_membership`.", "actions:hospitality.action.add_guest_feedback_entry:apply": "Apply `hospitality.action.add_guest_feedback_entry`.", "actions:hospitality.action.add_property_to_management_agreement:apply": "Apply `hospitality.action.add_property_to_management_agreement`.", "actions:hospitality.action.add_verified_invocation:apply": "Apply `hospitality.action.add_verified_invocation`.", "actions:hospitality.action.adjust_commission:apply": "Apply `hospitality.action.adjust_commission`.", "actions:hospitality.action.adjust_stock:apply": "Apply `hospitality.action.adjust_stock`.", "actions:hospitality.action.advance_maintenance_plan:apply": "Apply `hospitality.action.advance_maintenance_plan`.", "actions:hospitality.action.allocate_privacy_budget:apply": "Apply `hospitality.action.allocate_privacy_budget`.", "actions:hospitality.action.annotate_reservation:apply": "Apply `hospitality.action.annotate_reservation`.", "actions:hospitality.action.append_agent_thread_message:apply": "Apply `hospitality.action.append_agent_thread_message`.", "actions:hospitality.action.apply_channel_reservation:apply": "Apply `hospitality.action.apply_channel_reservation`.", "actions:hospitality.action.apply_deposit_to_folio:apply": "Apply `hospitality.action.apply_deposit_to_folio`.", "actions:hospitality.action.apply_fraud_assessment:apply": "Apply `hospitality.action.apply_fraud_assessment`.", "actions:hospitality.action.apply_message_triage:apply": "Apply `hospitality.action.apply_message_triage`.", "actions:hospitality.action.apply_pattern_remediation:apply": "Apply `hospitality.action.apply_pattern_remediation`.", "actions:hospitality.action.apply_payment:apply": "Apply `hospitality.action.apply_payment`.", "actions:hospitality.action.apply_rate_recommendation:apply": "Apply `hospitality.action.apply_rate_recommendation`.", "actions:hospitality.action.apply_restriction_recommendation:apply": "Apply `hospitality.action.apply_restriction_recommendation`.", "actions:hospitality.action.apply_sell_limit_recommendation:apply": "Apply `hospitality.action.apply_sell_limit_recommendation`.", "actions:hospitality.action.approve_agent_installation:apply": "Apply `hospitality.action.approve_agent_installation`.", "actions:hospitality.action.approve_federated_analysis_definition:apply": "Apply `hospitality.action.approve_federated_analysis_definition`.", "actions:hospitality.action.archive_automation:apply": "Apply `hospitality.action.archive_automation`.", "actions:hospitality.action.assemble_dispute_evidence:apply": "Apply `hospitality.action.assemble_dispute_evidence`.", "actions:hospitality.action.assemble_package_sale:apply": "Apply `hospitality.action.assemble_package_sale`.", "actions:hospitality.action.assemble_training_cohort:apply": "Apply `hospitality.action.assemble_training_cohort`.", "actions:hospitality.action.assign_approval_gate:apply": "Apply `hospitality.action.assign_approval_gate`.", "actions:hospitality.action.assign_brand_to_venue:apply": "Apply `hospitality.action.assign_brand_to_venue`.", "actions:hospitality.action.assign_housekeeping_task:apply": "Apply `hospitality.action.assign_housekeeping_task`.", "actions:hospitality.action.assign_operator_to_venue:apply": "Apply `hospitality.action.assign_operator_to_venue`.", "actions:hospitality.action.assign_room:apply": "Apply `hospitality.action.assign_room`.", "actions:hospitality.action.assign_room_for_reservation_room:apply": "Apply `hospitality.action.assign_room_for_reservation_room`.", "actions:hospitality.action.assign_work_order:apply": "Apply `hospitality.action.assign_work_order`.", "actions:hospitality.action.authorise_charge_with_review:apply": "Apply `hospitality.action.authorise_charge_with_review`.", "actions:hospitality.action.begin_appointment_service:apply": "Apply `hospitality.action.begin_appointment_service`.", "actions:hospitality.action.bind_commission_agreement:apply": "Apply `hospitality.action.bind_commission_agreement`.", "actions:hospitality.action.bind_commission_period:apply": "Apply `hospitality.action.bind_commission_period`.", "actions:hospitality.action.bind_comp_authority_policy:apply": "Apply `hospitality.action.bind_comp_authority_policy`.", "actions:hospitality.action.bind_development_pathway_definition:apply": "Apply `hospitality.action.bind_development_pathway_definition`.", "actions:hospitality.action.bind_folio_routing_rule:apply": "Apply `hospitality.action.bind_folio_routing_rule`.", "actions:hospitality.action.bind_ingredient:apply": "Apply `hospitality.action.bind_ingredient`.", "actions:hospitality.action.bind_recipe:apply": "Apply `hospitality.action.bind_recipe`.", "actions:hospitality.action.block_agent_registry_entry:apply": "Apply `hospitality.action.block_agent_registry_entry`.", "actions:hospitality.action.block_housekeeping_task:apply": "Apply `hospitality.action.block_housekeeping_task`.", "actions:hospitality.action.block_work_order:apply": "Apply `hospitality.action.block_work_order`.", "actions:hospitality.action.book_appointment:apply": "Apply `hospitality.action.book_appointment`.", "actions:hospitality.action.book_function_event:apply": "Apply `hospitality.action.book_function_event`.", "actions:hospitality.action.book_modality_session:apply": "Apply `hospitality.action.book_modality_session`.", "actions:hospitality.action.bump_ticket:apply": "Apply `hospitality.action.bump_ticket`.", "actions:hospitality.action.cancel_appointment:apply": "Apply `hospitality.action.cancel_appointment`.", "actions:hospitality.action.cancel_banquet_event_order:apply": "Apply `hospitality.action.cancel_banquet_event_order`.", "actions:hospitality.action.cancel_channel_reservation:apply": "Apply `hospitality.action.cancel_channel_reservation`.", "actions:hospitality.action.cancel_federated_run:apply": "Apply `hospitality.action.cancel_federated_run`.", "actions:hospitality.action.cancel_inspection_round:apply": "Apply `hospitality.action.cancel_inspection_round`.", "actions:hospitality.action.cancel_membership:apply": "Apply `hospitality.action.cancel_membership`.", "actions:hospitality.action.cancel_payment_request:apply": "Apply `hospitality.action.cancel_payment_request`.", "actions:hospitality.action.cancel_rail_instruction:apply": "Apply `hospitality.action.cancel_rail_instruction`.", "actions:hospitality.action.cancel_reservation:apply": "Apply `hospitality.action.cancel_reservation`.", "actions:hospitality.action.cancel_reservation_room:apply": "Apply `hospitality.action.cancel_reservation_room`.", "actions:hospitality.action.cancel_room_queue_entry:apply": "Apply `hospitality.action.cancel_room_queue_entry`.", "actions:hospitality.action.cancel_waitlist_entry:apply": "Apply `hospitality.action.cancel_waitlist_entry`.", "actions:hospitality.action.cancel_workflow_run:apply": "Apply `hospitality.action.cancel_workflow_run`.", "actions:hospitality.action.capture_authorised_charge:apply": "Apply `hospitality.action.capture_authorised_charge`.", "actions:hospitality.action.capture_guest_id:apply": "Apply `hospitality.action.capture_guest_id`.", "actions:hospitality.action.certify_metric:apply": "Apply `hospitality.action.certify_metric`.", "actions:hospitality.action.change_block_status:apply": "Apply `hospitality.action.change_block_status`.", "actions:hospitality.action.change_function_event_status:apply": "Apply `hospitality.action.change_function_event_status`.", "actions:hospitality.action.change_reservation_occupancy:apply": "Apply `hospitality.action.change_reservation_occupancy`.", "actions:hospitality.action.change_reservation_room_type:apply": "Apply `hospitality.action.change_reservation_room_type`.", "actions:hospitality.action.change_tier:apply": "Apply `hospitality.action.change_tier`.", "actions:hospitality.action.charge_virtual_card:apply": "Apply `hospitality.action.charge_virtual_card`.", "actions:hospitality.action.check_in:apply": "Apply `hospitality.action.check_in`.", "actions:hospitality.action.check_in_appointment:apply": "Apply `hospitality.action.check_in_appointment`.", "actions:hospitality.action.check_out:apply": "Apply `hospitality.action.check_out`.", "actions:hospitality.action.claim_lost_found_item:apply": "Apply `hospitality.action.claim_lost_found_item`.", "actions:hospitality.action.clear_rate_restrictions:apply": "Apply `hospitality.action.clear_rate_restrictions`.", "actions:hospitality.action.clear_table:apply": "Apply `hospitality.action.clear_table`.", "actions:hospitality.action.clock_in:apply": "Apply `hospitality.action.clock_in`.", "actions:hospitality.action.clock_out:apply": "Apply `hospitality.action.clock_out`.", "actions:hospitality.action.close_agent_thread:apply": "Apply `hospitality.action.close_agent_thread`.", "actions:hospitality.action.close_cashier_session:apply": "Apply `hospitality.action.close_cashier_session`.", "actions:hospitality.action.close_channel_connection:apply": "Apply `hospitality.action.close_channel_connection`.", "actions:hospitality.action.close_folio:apply": "Apply `hospitality.action.close_folio`.", "actions:hospitality.action.close_guest_feedback:apply": "Apply `hospitality.action.close_guest_feedback`.", "actions:hospitality.action.close_pattern_detection_run:apply": "Apply `hospitality.action.close_pattern_detection_run`.", "actions:hospitality.action.close_staff_employment_period:apply": "Apply `hospitality.action.close_staff_employment_period`.", "actions:hospitality.action.collect_cancellation_fee:apply": "Take a posted cancellation fee off the booking hold and a card the guest left — `POST /v1/reservations/{reservation_id}/cancellation-fee/collection`. The verb behind it is the card rail's own and is not applicable through `/v1/actions/{action}/apply`.", "actions:hospitality.action.collect_no_show_fee:apply": "Take an assessed fee off a card the guest left — `POST /v1/reservations/{reservation_id}/no-show-fee/collection` and `POST /v1/stays/{stay_id}/post-stay-charges/collection`. The verb behind them is the card rail's own and is not applicable through `/v1/actions/{action}/apply`.", "actions:hospitality.action.collect_tray:apply": "Apply `hospitality.action.collect_tray`.", "actions:hospitality.action.combine_reservations_as_share:apply": "Apply `hospitality.action.combine_reservations_as_share`.", "actions:hospitality.action.comp_check_line:apply": "Apply `hospitality.action.comp_check_line`.", "actions:hospitality.action.complete_appointment:apply": "Apply `hospitality.action.complete_appointment`.", "actions:hospitality.action.complete_channel_publication:apply": "Apply `hospitality.action.complete_channel_publication`.", "actions:hospitality.action.complete_connector_sync:apply": "Apply `hospitality.action.complete_connector_sync`.", "actions:hospitality.action.complete_housekeeping_task:apply": "Apply `hospitality.action.complete_housekeeping_task`.", "actions:hospitality.action.complete_inspection_round:apply": "Apply `hospitality.action.complete_inspection_round`.", "actions:hospitality.action.complete_work_order:apply": "Apply `hospitality.action.complete_work_order`.", "actions:hospitality.action.configure_agent_installation_dispatch:apply": "Apply `hospitality.action.configure_agent_installation_dispatch`.", "actions:hospitality.action.configure_channel_connection:apply": "Apply `hospitality.action.configure_channel_connection`.", "actions:hospitality.action.confirm_appointment:apply": "Apply `hospitality.action.confirm_appointment`.", "actions:hospitality.action.confirm_person_merge:apply": "Apply `hospitality.action.confirm_person_merge`.", "actions:hospitality.action.consume_package_component:apply": "Apply `hospitality.action.consume_package_component`.", "actions:hospitality.action.contest_fraud_network_signal:apply": "Apply `hospitality.action.contest_fraud_network_signal`.", "actions:hospitality.action.convert_group_request_to_reservation:apply": "Apply `hospitality.action.convert_group_request_to_reservation`.", "actions:hospitality.action.create_function_space:apply": "Apply `hospitality.action.create_function_space`.", "actions:hospitality.action.create_group_block:apply": "Apply `hospitality.action.create_group_block`.", "actions:hospitality.action.create_housekeeping_task:apply": "Apply `hospitality.action.create_housekeeping_task`.", "actions:hospitality.action.create_public_area_task:apply": "Apply `hospitality.action.create_public_area_task`.", "actions:hospitality.action.create_public_area_work_order:apply": "Apply `hospitality.action.create_public_area_work_order`.", "actions:hospitality.action.create_reservation:apply": "Apply `hospitality.action.create_reservation`.", "actions:hospitality.action.create_work_order:apply": "Apply `hospitality.action.create_work_order`.", "actions:hospitality.action.cut_over_connector:apply": "Cut a house over from its source PMS — `POST /v1/switchover/{connector_id}/cut-over`. The verb behind it is not applicable through `/v1/actions/{action}/apply`.", "actions:hospitality.action.decide_approval_gate:apply": "Apply `hospitality.action.decide_approval_gate`.", "actions:hospitality.action.decline_group_request:apply": "Apply `hospitality.action.decline_group_request`.", "actions:hospitality.action.define_access_purpose:apply": "Apply `hospitality.action.define_access_purpose`.", "actions:hospitality.action.define_automation:apply": "Apply `hospitality.action.define_automation`.", "actions:hospitality.action.define_checklist_template:apply": "Apply `hospitality.action.define_checklist_template`.", "actions:hospitality.action.define_fault_type:apply": "Apply `hospitality.action.define_fault_type`.", "actions:hospitality.action.define_feedback_label:apply": "Apply `hospitality.action.define_feedback_label`.", "actions:hospitality.action.define_grounding_scope:apply": "Apply `hospitality.action.define_grounding_scope`.", "actions:hospitality.action.define_maintenance_plan:apply": "Apply `hospitality.action.define_maintenance_plan`.", "actions:hospitality.action.define_material:apply": "Apply `hospitality.action.define_material`.", "actions:hospitality.action.define_metric:apply": "Apply `hospitality.action.define_metric`.", "actions:hospitality.action.define_round_template:apply": "Apply `hospitality.action.define_round_template`.", "actions:hospitality.action.define_stock_store:apply": "Apply `hospitality.action.define_stock_store`.", "actions:hospitality.action.define_worker_group:apply": "Apply `hospitality.action.define_worker_group`.", "actions:hospitality.action.delist_retail_product:apply": "Apply `hospitality.action.delist_retail_product`.", "actions:hospitality.action.deliver_room_service:apply": "Apply `hospitality.action.deliver_room_service`.", "actions:hospitality.action.deprecate_agent_registry_entry:apply": "Apply `hospitality.action.deprecate_agent_registry_entry`.", "actions:hospitality.action.deprecate_federated_program:apply": "Apply `hospitality.action.deprecate_federated_program`.", "actions:hospitality.action.deprecate_metric:apply": "Apply `hospitality.action.deprecate_metric`.", "actions:hospitality.action.deprecate_workflow_definition:apply": "Apply `hospitality.action.deprecate_workflow_definition`.", "actions:hospitality.action.detect_fraud_risk:apply": "Apply `hospitality.action.detect_fraud_risk`.", "actions:hospitality.action.detect_recurring_failure_pattern:apply": "Apply `hospitality.action.detect_recurring_failure_pattern`.", "actions:hospitality.action.dispatch_room_service:apply": "Apply `hospitality.action.dispatch_room_service`.", "actions:hospitality.action.dispatch_workflow_step_to_agent:apply": "Apply `hospitality.action.dispatch_workflow_step_to_agent`.", "actions:hospitality.action.dispose_lost_found_item:apply": "Apply `hospitality.action.dispose_lost_found_item`.", "actions:hospitality.action.draft_banquet_event_order:apply": "Apply `hospitality.action.draft_banquet_event_order`.", "actions:hospitality.action.enable_agent_installation:apply": "Apply `hospitality.action.enable_agent_installation`.", "actions:hospitality.action.end_deposit_policy:apply": "Apply `hospitality.action.end_deposit_policy`.", "actions:hospitality.action.end_residency:apply": "Apply `hospitality.action.end_residency`.", "actions:hospitality.action.end_tax_rule:apply": "Apply `hospitality.action.end_tax_rule`.", "actions:hospitality.action.enrol_member:apply": "Apply `hospitality.action.enrol_member`.", "actions:hospitality.action.enrol_property_in_program:apply": "Apply `hospitality.action.enrol_property_in_program`.", "actions:hospitality.action.enroll_federated_participant:apply": "Apply `hospitality.action.enroll_federated_participant`.", "actions:hospitality.action.escalate_via_fraud_assessment:apply": "Apply `hospitality.action.escalate_via_fraud_assessment`.", "actions:hospitality.action.escalate_via_pattern_assessment:apply": "Apply `hospitality.action.escalate_via_pattern_assessment`.", "actions:hospitality.action.escalate_via_triage:apply": "Apply `hospitality.action.escalate_via_triage`.", "actions:hospitality.action.execute_management_agreement:apply": "Apply `hospitality.action.execute_management_agreement`.", "actions:hospitality.action.expire_approval_gate:apply": "Apply `hospitality.action.expire_approval_gate`.", "actions:hospitality.action.expire_federated_run:apply": "Apply `hospitality.action.expire_federated_run`.", "actions:hospitality.action.expire_fraud_assessments:apply": "Apply `hospitality.action.expire_fraud_assessments`.", "actions:hospitality.action.expire_message_triages:apply": "Apply `hospitality.action.expire_message_triages`.", "actions:hospitality.action.expire_pattern_assessments:apply": "Apply `hospitality.action.expire_pattern_assessments`.", "actions:hospitality.action.expire_proposed_actions:apply": "Apply `hospitality.action.expire_proposed_actions`.", "actions:hospitality.action.expire_purpose_grant:apply": "Apply `hospitality.action.expire_purpose_grant`.", "actions:hospitality.action.expire_rate_recommendations:apply": "Apply `hospitality.action.expire_rate_recommendations`.", "actions:hospitality.action.expire_restriction_recommendations:apply": "Apply `hospitality.action.expire_restriction_recommendations`.", "actions:hospitality.action.expire_retained_record:apply": "Apply `hospitality.action.expire_retained_record`.", "actions:hospitality.action.expire_sell_limit_recommendations:apply": "Apply `hospitality.action.expire_sell_limit_recommendations`.", "actions:hospitality.action.expire_workflow_run:apply": "Apply `hospitality.action.expire_workflow_run`.", "actions:hospitality.action.fire_course:apply": "Apply `hospitality.action.fire_course`.", "actions:hospitality.action.forfeit_deposit:apply": "Apply `hospitality.action.forfeit_deposit`.", "actions:hospitality.action.freeze_membership:apply": "Apply `hospitality.action.freeze_membership`.", "actions:hospitality.action.generate_housekeeping_tasks:apply": "Apply `hospitality.action.generate_housekeeping_tasks`.", "actions:hospitality.action.grant_consent:apply": "Apply `hospitality.action.grant_consent`.", "actions:hospitality.action.hold_commission:apply": "Apply `hospitality.action.hold_commission`.", "actions:hospitality.action.issue_access_credential:apply": "Apply `hospitality.action.issue_access_credential`.", "actions:hospitality.action.issue_banquet_event_order:apply": "Apply `hospitality.action.issue_banquet_event_order`.", "actions:hospitality.action.issue_invoice:apply": "Apply `hospitality.action.issue_invoice`.", "actions:hospitality.action.issue_stock:apply": "Apply `hospitality.action.issue_stock`.", "actions:hospitality.action.lapse_waitlist_offer:apply": "Apply `hospitality.action.lapse_waitlist_offer`.", "actions:hospitality.action.launch_retail_product_line:apply": "Apply `hospitality.action.launch_retail_product_line`.", "actions:hospitality.action.lift_rate_restriction:apply": "Apply `hospitality.action.lift_rate_restriction`.", "actions:hospitality.action.list_retail_product_at_property:apply": "Apply `hospitality.action.list_retail_product_at_property`.", "actions:hospitality.action.list_retail_product_at_venue:apply": "Apply `hospitality.action.list_retail_product_at_venue`.", "actions:hospitality.action.log_pre_shift_lineup:apply": "Apply `hospitality.action.log_pre_shift_lineup`.", "actions:hospitality.action.map_channel_inventory:apply": "Apply `hospitality.action.map_channel_inventory`.", "actions:hospitality.action.mark_appointment_no_show:apply": "Apply `hospitality.action.mark_appointment_no_show`.", "actions:hospitality.action.mark_request_overdue:apply": "Apply `hospitality.action.mark_request_overdue`.", "actions:hospitality.action.mark_reservation_no_show:apply": "Apply `hospitality.action.mark_reservation_no_show`.", "actions:hospitality.action.match_waitlist_entries:apply": "Apply `hospitality.action.match_waitlist_entries`.", "actions:hospitality.action.materialise_channel_mix_snapshot:apply": "Apply `hospitality.action.materialise_channel_mix_snapshot`.", "actions:hospitality.action.materialise_derived_rate:apply": "Apply `hospitality.action.materialise_derived_rate`.", "actions:hospitality.action.message_guest:apply": "Apply `hospitality.action.message_guest`.", "actions:hospitality.action.modify_reservation_dates:apply": "Apply `hospitality.action.modify_reservation_dates`.", "actions:hospitality.action.move_room:apply": "Apply `hospitality.action.move_room`.", "actions:hospitality.action.offer_stay:apply": "Apply `hospitality.action.offer_stay`.", "actions:hospitality.action.offer_waitlist_entry:apply": "Apply `hospitality.action.offer_waitlist_entry`.", "actions:hospitality.action.onboard_staff_member:apply": "Apply `hospitality.action.onboard_staff_member`.", "actions:hospitality.action.open_agent_thread:apply": "Apply `hospitality.action.open_agent_thread`.", "actions:hospitality.action.open_approval_gate:apply": "Apply `hospitality.action.open_approval_gate`.", "actions:hospitality.action.open_business_date:apply": "Apply `hospitality.action.open_business_date`.", "actions:hospitality.action.open_cashier_session:apply": "Apply `hospitality.action.open_cashier_session`.", "actions:hospitality.action.open_channel_connection:apply": "Apply `hospitality.action.open_channel_connection`.", "actions:hospitality.action.open_check:apply": "Apply `hospitality.action.open_check`.", "actions:hospitality.action.open_company_ar_folio:apply": "Apply `hospitality.action.open_company_ar_folio`.", "actions:hospitality.action.open_group_master_folio:apply": "Apply `hospitality.action.open_group_master_folio`.", "actions:hospitality.action.open_pattern_detection_run:apply": "Apply `hospitality.action.open_pattern_detection_run`.", "actions:hospitality.action.open_rebate_folio:apply": "Apply `hospitality.action.open_rebate_folio`.", "actions:hospitality.action.open_staff_employment_period:apply": "Apply `hospitality.action.open_staff_employment_period`.", "actions:hospitality.action.pause_automation:apply": "Apply `hospitality.action.pause_automation`.", "actions:hospitality.action.pause_channel_connection:apply": "Apply `hospitality.action.pause_channel_connection`.", "actions:hospitality.action.pause_connector:apply": "Apply `hospitality.action.pause_connector`.", "actions:hospitality.action.pay_commission_batch:apply": "Apply `hospitality.action.pay_commission_batch`.", "actions:hospitality.action.pick_up_block_reservation:apply": "Apply `hospitality.action.pick_up_block_reservation`.", "actions:hospitality.action.pin_object_property:apply": "Apply `hospitality.action.pin_object_property`.", "actions:hospitality.action.post_banquet_event_charges:apply": "Apply `hospitality.action.post_banquet_event_charges`.", "actions:hospitality.action.post_cancellation_fee:apply": "Apply `hospitality.action.post_cancellation_fee`.", "actions:hospitality.action.post_charge:apply": "Apply `hospitality.action.post_charge`.", "actions:hospitality.action.post_charge_by_credential:apply": "Apply `hospitality.action.post_charge_by_credential`.", "actions:hospitality.action.post_departed_charge:apply": "Apply `hospitality.action.post_departed_charge`.", "actions:hospitality.action.post_external_charge:apply": "Apply `hospitality.action.post_external_charge`.", "actions:hospitality.action.post_housekeeping_briefing:apply": "Apply `hospitality.action.post_housekeeping_briefing`.", "actions:hospitality.action.post_package_profit_loss:apply": "Apply `hospitality.action.post_package_profit_loss`.", "actions:hospitality.action.postpone_work_order:apply": "Apply `hospitality.action.postpone_work_order`.", "actions:hospitality.action.prescribe_protocol:apply": "Apply `hospitality.action.prescribe_protocol`.", "actions:hospitality.action.propose_action:apply": "Apply `hospitality.action.propose_action`.", "actions:hospitality.action.propose_person_match:apply": "Apply `hospitality.action.propose_person_match`.", "actions:hospitality.action.publish_federated_analysis_definition:apply": "Apply `hospitality.action.publish_federated_analysis_definition`.", "actions:hospitality.action.publish_federated_output:apply": "Apply `hospitality.action.publish_federated_output`.", "actions:hospitality.action.publish_federated_program:apply": "Apply `hospitality.action.publish_federated_program`.", "actions:hospitality.action.publish_model_version:apply": "Apply `hospitality.action.publish_model_version`.", "actions:hospitality.action.publish_workflow_definition:apply": "Apply `hospitality.action.publish_workflow_definition`.", "actions:hospitality.action.quarantine_federated_output:apply": "Apply `hospitality.action.quarantine_federated_output`.", "actions:hospitality.action.queue_reservation_for_room:apply": "Apply `hospitality.action.queue_reservation_for_room`.", "actions:hospitality.action.quote_group_block:apply": "Apply `hospitality.action.quote_group_block`.", "actions:hospitality.action.raise_maintenance_work_order:apply": "Apply `hospitality.action.raise_maintenance_work_order`.", "actions:hospitality.action.raise_work_order_from_feedback:apply": "Apply `hospitality.action.raise_work_order_from_feedback`.", "actions:hospitality.action.recall_ticket:apply": "Apply `hospitality.action.recall_ticket`.", "actions:hospitality.action.receive_channel_reservation:apply": "Apply `hospitality.action.receive_channel_reservation`.", "actions:hospitality.action.receive_stock:apply": "Apply `hospitality.action.receive_stock`.", "actions:hospitality.action.reclaim_housekeeping_task:apply": "Apply `hospitality.action.reclaim_housekeeping_task`.", "actions:hospitality.action.reclaim_work_order:apply": "Apply `hospitality.action.reclaim_work_order`.", "actions:hospitality.action.recognise_person:apply": "Apply `hospitality.action.recognise_person`.", "actions:hospitality.action.recommend_rate:apply": "Apply `hospitality.action.recommend_rate`.", "actions:hospitality.action.recommend_restriction:apply": "Apply `hospitality.action.recommend_restriction`.", "actions:hospitality.action.recommend_sell_limit:apply": "Apply `hospitality.action.recommend_sell_limit`.", "actions:hospitality.action.reconcile_folio_balance:apply": "Apply `hospitality.action.reconcile_folio_balance`.", "actions:hospitality.action.record_assessment:apply": "Apply `hospitality.action.record_assessment`.", "actions:hospitality.action.record_booking_origin:apply": "Apply `hospitality.action.record_booking_origin`.", "actions:hospitality.action.record_brand_operator_cost:apply": "Apply `hospitality.action.record_brand_operator_cost`.", "actions:hospitality.action.record_breakfast_taken:apply": "Apply `hospitality.action.record_breakfast_taken`.", "actions:hospitality.action.record_cashier_transaction:apply": "Apply `hospitality.action.record_cashier_transaction`.", "actions:hospitality.action.record_checklist_result:apply": "Apply `hospitality.action.record_checklist_result`.", "actions:hospitality.action.record_checkpoint:apply": "Apply `hospitality.action.record_checkpoint`.", "actions:hospitality.action.record_companion_relationship:apply": "Apply `hospitality.action.record_companion_relationship`.", "actions:hospitality.action.record_compensation_result:apply": "Apply `hospitality.action.record_compensation_result`.", "actions:hospitality.action.record_demand_forecast:apply": "Apply `hospitality.action.record_demand_forecast`.", "actions:hospitality.action.record_deposit_payment:apply": "Apply `hospitality.action.record_deposit_payment`.", "actions:hospitality.action.record_dispute_evidence_submission:apply": "Submit a chargeback's evidence packet to the issuer — `POST /v1/payment-disputes/{dispute_id}/evidence/submission`. The verb behind it records what the processor did and is the card rail's own; it is not applicable through `/v1/actions/{action}/apply`.", "actions:hospitality.action.record_external_payment:apply": "Apply `hospitality.action.record_external_payment`.", "actions:hospitality.action.record_external_refund:apply": "Apply `hospitality.action.record_external_refund`.", "actions:hospitality.action.record_federated_aggregation_result:apply": "Apply `hospitality.action.record_federated_aggregation_result`.", "actions:hospitality.action.record_federated_contribution:apply": "Apply `hospitality.action.record_federated_contribution`.", "actions:hospitality.action.record_federated_privacy_incident:apply": "Apply `hospitality.action.record_federated_privacy_incident`.", "actions:hospitality.action.record_function_event_actuals:apply": "Apply `hospitality.action.record_function_event_actuals`.", "actions:hospitality.action.record_guest_feedback:apply": "Apply `hospitality.action.record_guest_feedback`.", "actions:hospitality.action.record_guest_message:apply": "Apply `hospitality.action.record_guest_message`.", "actions:hospitality.action.record_hold_top_up:apply": "Top up an in-house stay's card hold now — `POST /v1/stays/{stay_id}/holds/top-up`. The verb behind it is the card rail's own and is not applied directly.", "actions:hospitality.action.record_housekeeping_task_entry:apply": "Apply `hospitality.action.record_housekeeping_task_entry`.", "actions:hospitality.action.record_inference:apply": "Apply `hospitality.action.record_inference`.", "actions:hospitality.action.record_ingredient_cost:apply": "Apply `hospitality.action.record_ingredient_cost`.", "actions:hospitality.action.record_labour_cost:apply": "Apply `hospitality.action.record_labour_cost`.", "actions:hospitality.action.record_lost_found_item:apply": "Apply `hospitality.action.record_lost_found_item`.", "actions:hospitality.action.record_pattern_recurrence_outcome:apply": "Apply `hospitality.action.record_pattern_recurrence_outcome`.", "actions:hospitality.action.record_payment_dispute:apply": "Apply `hospitality.action.record_payment_dispute`.", "actions:hospitality.action.record_recognition_event:apply": "Apply `hospitality.action.record_recognition_event`.", "actions:hospitality.action.record_service_recovery:apply": "Apply `hospitality.action.record_service_recovery`.", "actions:hospitality.action.record_staff_certification:apply": "Apply `hospitality.action.record_staff_certification`.", "actions:hospitality.action.record_turnaway:apply": "Apply `hospitality.action.record_turnaway`.", "actions:hospitality.action.record_utility_cost:apply": "Apply `hospitality.action.record_utility_cost`.", "actions:hospitality.action.record_venue_visit:apply": "Apply `hospitality.action.record_venue_visit`.", "actions:hospitality.action.record_work_order_entry:apply": "Apply `hospitality.action.record_work_order_entry`.", "actions:hospitality.action.recount_stock_level:apply": "Apply `hospitality.action.recount_stock_level`.", "actions:hospitality.action.redact_person_recognition:apply": "Apply `hospitality.action.redact_person_recognition`.", "actions:hospitality.action.refresh_folio_aging:apply": "Apply `hospitality.action.refresh_folio_aging`.", "actions:hospitality.action.refresh_person_projections:apply": "Apply `hospitality.action.refresh_person_projections`.", "actions:hospitality.action.refresh_recipe_pour_cost:apply": "Apply `hospitality.action.refresh_recipe_pour_cost`.", "actions:hospitality.action.refresh_staff_projections:apply": "Apply `hospitality.action.refresh_staff_projections`.", "actions:hospitality.action.refund_payment:apply": "Apply `hospitality.action.refund_payment`.", "actions:hospitality.action.register_agent:apply": "Apply `hospitality.action.register_agent`.", "actions:hospitality.action.register_asset:apply": "Apply `hospitality.action.register_asset`.", "actions:hospitality.action.register_connector:apply": "Apply `hospitality.action.register_connector`.", "actions:hospitality.action.register_device:apply": "Apply `hospitality.action.register_device`.", "actions:hospitality.action.register_guest:apply": "Apply `hospitality.action.register_guest`.", "actions:hospitality.action.register_outlet:apply": "Apply `hospitality.action.register_outlet`.", "actions:hospitality.action.register_property:apply": "Apply `hospitality.action.register_property`.", "actions:hospitality.action.register_public_area:apply": "Apply `hospitality.action.register_public_area`.", "actions:hospitality.action.register_rate_plan:apply": "Apply `hospitality.action.register_rate_plan`.", "actions:hospitality.action.register_room:apply": "Apply `hospitality.action.register_room`.", "actions:hospitality.action.register_room_type:apply": "Apply `hospitality.action.register_room_type`.", "actions:hospitality.action.reject_channel_reservation:apply": "Apply `hospitality.action.reject_channel_reservation`.", "actions:hospitality.action.reject_fraud_assessment:apply": "Apply `hospitality.action.reject_fraud_assessment`.", "actions:hospitality.action.reject_message_triage:apply": "Apply `hospitality.action.reject_message_triage`.", "actions:hospitality.action.reject_pattern_assessment:apply": "Apply `hospitality.action.reject_pattern_assessment`.", "actions:hospitality.action.reject_person_match:apply": "Apply `hospitality.action.reject_person_match`.", "actions:hospitality.action.reject_proposed_action:apply": "Apply `hospitality.action.reject_proposed_action`.", "actions:hospitality.action.reject_rate_recommendation:apply": "Apply `hospitality.action.reject_rate_recommendation`.", "actions:hospitality.action.reject_restriction_recommendation:apply": "Apply `hospitality.action.reject_restriction_recommendation`.", "actions:hospitality.action.reject_sell_limit_recommendation:apply": "Apply `hospitality.action.reject_sell_limit_recommendation`.", "actions:hospitality.action.release_block:apply": "Apply `hospitality.action.release_block`.", "actions:hospitality.action.release_commission_hold:apply": "Apply `hospitality.action.release_commission_hold`.", "actions:hospitality.action.release_object_property_pin:apply": "Apply `hospitality.action.release_object_property_pin`.", "actions:hospitality.action.remove_banquet_order_line:apply": "Apply `hospitality.action.remove_banquet_order_line`.", "actions:hospitality.action.renew_membership:apply": "Apply `hospitality.action.renew_membership`.", "actions:hospitality.action.reopen_folio:apply": "Apply `hospitality.action.reopen_folio`.", "actions:hospitality.action.repoint_connector_mapping:apply": "Apply `hospitality.action.repoint_connector_mapping`.", "actions:hospitality.action.request_agent_installation:apply": "Apply `hospitality.action.request_agent_installation`.", "actions:hospitality.action.request_approval_gate:apply": "Apply `hospitality.action.request_approval_gate`.", "actions:hospitality.action.request_payment:apply": "Apply `hospitality.action.request_payment`.", "actions:hospitality.action.request_purpose_grant:apply": "Apply `hospitality.action.request_purpose_grant`.", "actions:hospitality.action.reschedule_appointment:apply": "Apply `hospitality.action.reschedule_appointment`.", "actions:hospitality.action.reschedule_function_event:apply": "Apply `hospitality.action.reschedule_function_event`.", "actions:hospitality.action.resend_authentication_chase:apply": "Apply `hospitality.action.resend_authentication_chase`.", "actions:hospitality.action.resolve_guest_feedback:apply": "Apply `hospitality.action.resolve_guest_feedback`.", "actions:hospitality.action.resolve_payment_refund:apply": "Apply `hospitality.action.resolve_payment_refund`.", "actions:hospitality.action.resolve_payment_review:apply": "Decide a hold held for review — keep it (`POST /v1/fraud-risk-assessments/{assessment_id}/keep`) or, with the void grant, block it (`.../block`). The verb behind it is the card rail's own and is not applied directly; both routes also take `markings:internal.restricted:read`.", "actions:hospitality.action.resolve_room_discrepancy:apply": "Apply `hospitality.action.resolve_room_discrepancy`.", "actions:hospitality.action.restate_channel_reservation:apply": "Apply `hospitality.action.restate_channel_reservation`.", "actions:hospitality.action.resume_channel_connection:apply": "Apply `hospitality.action.resume_channel_connection`.", "actions:hospitality.action.resume_connector:apply": "Apply `hospitality.action.resume_connector`.", "actions:hospitality.action.resume_work_order:apply": "Apply `hospitality.action.resume_work_order`.", "actions:hospitality.action.retime_housekeeping_task:apply": "Apply `hospitality.action.retime_housekeeping_task`.", "actions:hospitality.action.retire_access_purpose:apply": "Apply `hospitality.action.retire_access_purpose`.", "actions:hospitality.action.retire_agent_eval_case:apply": "Apply `hospitality.action.retire_agent_eval_case`.", "actions:hospitality.action.retire_asset:apply": "Apply `hospitality.action.retire_asset`.", "actions:hospitality.action.retire_board_sort_pattern:apply": "Apply `hospitality.action.retire_board_sort_pattern`.", "actions:hospitality.action.retire_checklist_template:apply": "Apply `hospitality.action.retire_checklist_template`.", "actions:hospitality.action.retire_connector:apply": "Apply `hospitality.action.retire_connector`.", "actions:hospitality.action.retire_fault_type:apply": "Apply `hospitality.action.retire_fault_type`.", "actions:hospitality.action.retire_grounding_scope:apply": "Apply `hospitality.action.retire_grounding_scope`.", "actions:hospitality.action.retire_housekeeping_credit_rule:apply": "Apply `hospitality.action.retire_housekeeping_credit_rule`.", "actions:hospitality.action.retire_maintenance_plan:apply": "Apply `hospitality.action.retire_maintenance_plan`.", "actions:hospitality.action.retire_material:apply": "Apply `hospitality.action.retire_material`.", "actions:hospitality.action.retire_payment_card:apply": "Apply `hospitality.action.retire_payment_card`.", "actions:hospitality.action.retire_public_area:apply": "Apply `hospitality.action.retire_public_area`.", "actions:hospitality.action.retire_round_template:apply": "Apply `hospitality.action.retire_round_template`.", "actions:hospitality.action.retire_worker_group:apply": "Apply `hospitality.action.retire_worker_group`.", "actions:hospitality.action.retrain_shard:apply": "Apply `hospitality.action.retrain_shard`.", "actions:hospitality.action.retry_guest_message_delivery:apply": "Apply `hospitality.action.retry_guest_message_delivery`.", "actions:hospitality.action.return_lost_found_item:apply": "Apply `hospitality.action.return_lost_found_item`.", "actions:hospitality.action.return_room_to_service:apply": "Apply `hospitality.action.return_room_to_service`.", "actions:hospitality.action.reverse_charge:apply": "Apply `hospitality.action.reverse_charge`.", "actions:hospitality.action.review_agent_registry_entry:apply": "Apply `hospitality.action.review_agent_registry_entry`.", "actions:hospitality.action.revise_metric:apply": "Apply `hospitality.action.revise_metric`.", "actions:hospitality.action.revoke_access_credential:apply": "Apply `hospitality.action.revoke_access_credential`.", "actions:hospitality.action.revoke_consent:apply": "Apply `hospitality.action.revoke_consent`.", "actions:hospitality.action.revoke_purpose_grant:apply": "Apply `hospitality.action.revoke_purpose_grant`.", "actions:hospitality.action.revoke_staff_certification:apply": "Apply `hospitality.action.revoke_staff_certification`.", "actions:hospitality.action.revoke_tax_exemption:apply": "Apply `hospitality.action.revoke_tax_exemption`.", "actions:hospitality.action.roll_back_connector_cutover:apply": "Roll a cutover back to the source PMS — `POST /v1/switchover/{connector_id}/roll-back`. The verb behind it is not applicable through `/v1/actions/{action}/apply`.", "actions:hospitality.action.run_automation_now:apply": "Apply `hospitality.action.run_automation_now`.", "actions:hospitality.action.run_night_audit:apply": "Apply `hospitality.action.run_night_audit`.", "actions:hospitality.action.schedule_work_order:apply": "Apply `hospitality.action.schedule_work_order`.", "actions:hospitality.action.separate_share:apply": "Apply `hospitality.action.separate_share`.", "actions:hospitality.action.set_asset_status:apply": "Apply `hospitality.action.set_asset_status`.", "actions:hospitality.action.set_availability:apply": "Apply `hospitality.action.set_availability`.", "actions:hospitality.action.set_bed_configuration:apply": "Apply `hospitality.action.set_bed_configuration`.", "actions:hospitality.action.set_block_allocation:apply": "Apply `hospitality.action.set_block_allocation`.", "actions:hospitality.action.set_board_sort_pattern:apply": "Apply `hospitality.action.set_board_sort_pattern`.", "actions:hospitality.action.set_cancellation_policy:apply": "Apply `hospitality.action.set_cancellation_policy`.", "actions:hospitality.action.set_checkout_satisfaction:apply": "Apply `hospitality.action.set_checkout_satisfaction`.", "actions:hospitality.action.set_credit_limit_overage:apply": "Apply `hospitality.action.set_credit_limit_overage`.", "actions:hospitality.action.set_deposit_policy:apply": "Apply `hospitality.action.set_deposit_policy`.", "actions:hospitality.action.set_device_status:apply": "Apply `hospitality.action.set_device_status`.", "actions:hospitality.action.set_fnb_open_checks_policy:apply": "Apply `hospitality.action.set_fnb_open_checks_policy`.", "actions:hospitality.action.set_function_event_counts:apply": "Apply `hospitality.action.set_function_event_counts`.", "actions:hospitality.action.set_green_stay:apply": "Apply `hospitality.action.set_green_stay`.", "actions:hospitality.action.set_guest_feedback_labels:apply": "Apply `hospitality.action.set_guest_feedback_labels`.", "actions:hospitality.action.set_guest_replies:apply": "Apply `hospitality.action.set_guest_replies`.", "actions:hospitality.action.set_hold_top_up:apply": "Apply `hospitality.action.set_hold_top_up`.", "actions:hospitality.action.set_housekeeping_credit_rule:apply": "Apply `hospitality.action.set_housekeeping_credit_rule`.", "actions:hospitality.action.set_incidental_hold_policy:apply": "Apply `hospitality.action.set_incidental_hold_policy`.", "actions:hospitality.action.set_no_show_posting_rule:apply": "Apply `hospitality.action.set_no_show_posting_rule`.", "actions:hospitality.action.set_outlet_meal_periods:apply": "Apply `hospitality.action.set_outlet_meal_periods`.", "actions:hospitality.action.set_payment_request_messaging:apply": "Apply `hospitality.action.set_payment_request_messaging`.", "actions:hospitality.action.set_post_stay_charging:apply": "Apply `hospitality.action.set_post_stay_charging`.", "actions:hospitality.action.set_posting_rules:apply": "Apply `hospitality.action.set_posting_rules`.", "actions:hospitality.action.set_public_area_reader_code:apply": "Apply `hospitality.action.set_public_area_reader_code`.", "actions:hospitality.action.set_rate_restriction:apply": "Apply `hospitality.action.set_rate_restriction`.", "actions:hospitality.action.set_rates:apply": "Apply `hospitality.action.set_rates`.", "actions:hospitality.action.set_request_urgency_window:apply": "Apply `hospitality.action.set_request_urgency_window`.", "actions:hospitality.action.set_room_housekeeping_status:apply": "Apply `hospitality.action.set_room_housekeeping_status`.", "actions:hospitality.action.set_room_reader_code:apply": "Apply `hospitality.action.set_room_reader_code`.", "actions:hospitality.action.set_sca_chase:apply": "Apply `hospitality.action.set_sca_chase`.", "actions:hospitality.action.set_shift_credit_target:apply": "Apply `hospitality.action.set_shift_credit_target`.", "actions:hospitality.action.set_staff_push_topics:apply": "Apply `hospitality.action.set_staff_push_topics`.", "actions:hospitality.action.set_staff_sort_preference:apply": "Apply `hospitality.action.set_staff_sort_preference`.", "actions:hospitality.action.set_stock_reorder_point:apply": "Apply `hospitality.action.set_stock_reorder_point`.", "actions:hospitality.action.set_tax_exemption:apply": "Apply `hospitality.action.set_tax_exemption`.", "actions:hospitality.action.set_tax_rule:apply": "Apply `hospitality.action.set_tax_rule`.", "actions:hospitality.action.set_waitlist_offer_messaging:apply": "Apply `hospitality.action.set_waitlist_offer_messaging`.", "actions:hospitality.action.set_worker_group_members:apply": "Apply `hospitality.action.set_worker_group_members`.", "actions:hospitality.action.settle_appointment:apply": "Apply `hospitality.action.settle_appointment`.", "actions:hospitality.action.settle_check:apply": "Apply `hospitality.action.settle_check`.", "actions:hospitality.action.settle_commission_without_payment:apply": "Apply `hospitality.action.settle_commission_without_payment`.", "actions:hospitality.action.settle_folio_to_ar:apply": "Apply `hospitality.action.settle_folio_to_ar`.", "actions:hospitality.action.sign_registration_card:apply": "Apply `hospitality.action.sign_registration_card`.", "actions:hospitality.action.skip_housekeeping_task:apply": "Apply `hospitality.action.skip_housekeeping_task`.", "actions:hospitality.action.split_person_merge:apply": "Apply `hospitality.action.split_person_merge`.", "actions:hospitality.action.start_channel_publication:apply": "Apply `hospitality.action.start_channel_publication`.", "actions:hospitality.action.start_connector_sync:apply": "Apply `hospitality.action.start_connector_sync`.", "actions:hospitality.action.start_federated_run:apply": "Apply `hospitality.action.start_federated_run`.", "actions:hospitality.action.start_housekeeping_task:apply": "Apply `hospitality.action.start_housekeeping_task`.", "actions:hospitality.action.start_inspection_round:apply": "Apply `hospitality.action.start_inspection_round`.", "actions:hospitality.action.start_residency:apply": "Apply `hospitality.action.start_residency`.", "actions:hospitality.action.start_work_order:apply": "Apply `hospitality.action.start_work_order`.", "actions:hospitality.action.start_workflow_run:apply": "Apply `hospitality.action.start_workflow_run`.", "actions:hospitality.action.store_lost_found_item:apply": "Apply `hospitality.action.store_lost_found_item`.", "actions:hospitality.action.store_payment_card:apply": "Apply `hospitality.action.store_payment_card`.", "actions:hospitality.action.submit_owner_statement:apply": "Apply `hospitality.action.submit_owner_statement`.", "actions:hospitality.action.submit_property_budget:apply": "Apply `hospitality.action.submit_property_budget`.", "actions:hospitality.action.sunset_retail_product_line:apply": "Apply `hospitality.action.sunset_retail_product_line`.", "actions:hospitality.action.supersede_package:apply": "Apply `hospitality.action.supersede_package`.", "actions:hospitality.action.suspend_agent_installation:apply": "Apply `hospitality.action.suspend_agent_installation`.", "actions:hospitality.action.suspend_channel_connection:apply": "Apply `hospitality.action.suspend_channel_connection`.", "actions:hospitality.action.take_room_out_of_order:apply": "Apply `hospitality.action.take_room_out_of_order`.", "actions:hospitality.action.take_room_out_of_service:apply": "Apply `hospitality.action.take_room_out_of_service`.", "actions:hospitality.action.terminate_management_agreement:apply": "Apply `hospitality.action.terminate_management_agreement`.", "actions:hospitality.action.transfer_booking_hold:apply": "Apply `hospitality.action.transfer_booking_hold`.", "actions:hospitality.action.transfer_charge:apply": "Apply `hospitality.action.transfer_charge`.", "actions:hospitality.action.transfer_legacy_membership:apply": "Apply `hospitality.action.transfer_legacy_membership`.", "actions:hospitality.action.transfer_stock:apply": "Apply `hospitality.action.transfer_stock`.", "actions:hospitality.action.transition_venue_brand:apply": "Apply `hospitality.action.transition_venue_brand`.", "actions:hospitality.action.triage_guest_message:apply": "Apply `hospitality.action.triage_guest_message`.", "actions:hospitality.action.unfreeze_membership:apply": "Apply `hospitality.action.unfreeze_membership`.", "actions:hospitality.action.unmap_channel_inventory:apply": "Apply `hospitality.action.unmap_channel_inventory`.", "actions:hospitality.action.update_automation:apply": "Apply `hospitality.action.update_automation`.", "actions:hospitality.action.update_banquet_order_line:apply": "Apply `hospitality.action.update_banquet_order_line`.", "actions:hospitality.action.update_coaching_plan:apply": "Apply `hospitality.action.update_coaching_plan`.", "actions:hospitality.action.update_company_billing:apply": "Apply `hospitality.action.update_company_billing`.", "actions:hospitality.action.update_function_space:apply": "Apply `hospitality.action.update_function_space`.", "actions:hospitality.action.update_guest_profile:apply": "Apply `hospitality.action.update_guest_profile`.", "actions:hospitality.action.update_pricing_strategy:apply": "Apply `hospitality.action.update_pricing_strategy`.", "actions:hospitality.action.update_service_philosophy:apply": "Apply `hospitality.action.update_service_philosophy`.", "actions:hospitality.action.update_staff_member_profile:apply": "Apply `hospitality.action.update_staff_member_profile`.", "actions:hospitality.action.verify_staff_certification:apply": "Apply `hospitality.action.verify_staff_certification`.", "actions:hospitality.action.void_authorisation:apply": "Release a hold without taking it — `POST /v1/payments/{payment_id}/void`. The verb behind it is the card rail's own and is not applied directly.", "actions:hospitality.action.void_brand_operator_cost:apply": "Apply `hospitality.action.void_brand_operator_cost`.", "actions:hospitality.action.void_check_line:apply": "Apply `hospitality.action.void_check_line`.", "actions:hospitality.action.void_labour_cost:apply": "Apply `hospitality.action.void_labour_cost`.", "actions:hospitality.action.void_shift:apply": "Apply `hospitality.action.void_shift`.", "actions:hospitality.action.void_utility_cost:apply": "Apply `hospitality.action.void_utility_cost`.", "actions:hospitality.action.void_work_order:apply": "Apply `hospitality.action.void_work_order`.", "actions:hospitality.action.waitlist_reservation_request:apply": "Apply `hospitality.action.waitlist_reservation_request`.", "actions:hospitality.action.withdraw_federated_participant:apply": "Apply `hospitality.action.withdraw_federated_participant`.", "actions:hospitality.action.withdraw_fraud_signal:apply": "Apply `hospitality.action.withdraw_fraud_signal`.", "analytics:read": "Read conformed metrics over their projection-maintained rollups (`GET /v1/metrics/{name}`) and the typed fact queries (`GET /v1/analytics/booking-pace`).", "analytics:write": "Trigger analytics fact writes — today the on-demand booking-pace snapshot capture (`POST /v1/analytics/booking-pace/capture`).", "erasure:write": "Force immediate GDPR Article 17 hard-delete of a single `(object_type, object_id)`, bypassing the retention floor. Tenant-level — issued narrowly to a small audited set of admin clients within the tenant.", "events:read": "Read the event log and subscribe to the live event stream.", "functions:invoke": "Catch-all invoke scope for every registered function. Issue per-function scopes (`functions:{api_name}:invoke`) instead when granting narrowly to a service account.", "markings:internal.restricted:read": "Clearance (proposal 0035) to read `internal.restricted`-marked values — fraud assessments' bands and Radar snapshots, agent proposals, recovery traces — which are otherwise read back null. Required beside the grant by the card-review routes (`POST /v1/fraud-risk-assessments/{assessment_id}/keep` and `.../block`): the desk decides only what it can see; and beside `tenant_admin:write` by the platform's review of a contested Watchtower answer (`/v1/watchtower/…`). `markings:*:read` grants it too.", "markings:payment.token:read": "Clearance (proposal 0035) to read `payment.token`-marked values — the processor's handles on a card or a payment, which are otherwise read back null. Required beside `tenant_admin:write` by `GET /v1/merchant-accounts/{merchant_account_id}/card-export`.", "objects:hospitality.access_credential:read": "Read `hospitality.access_credential` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.access_purpose:read": "Read `hospitality.access_purpose` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.agent_eval_case:read": "Read `hospitality.agent_eval_case` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.agent_installation:read": "Read `hospitality.agent_installation` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.agent_registry_entry:read": "Read `hospitality.agent_registry_entry` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.agent_thread:read": "Read `hospitality.agent_thread` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.agent_thread_message:read": "Read `hospitality.agent_thread_message` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.allergy_alert:read": "Read `hospitality.allergy_alert` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.appointment:read": "Read `hospitality.appointment` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.approval_decision:read": "Read `hospitality.approval_decision` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.approval_gate:read": "Read `hospitality.approval_gate` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.asset:read": "Read `hospitality.asset` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.automation:read": "Read `hospitality.automation` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.automation_run:read": "Read `hospitality.automation_run` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.availability_day:read": "Read `hospitality.availability_day` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.banquet_event_order:read": "Read `hospitality.banquet_event_order` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.banquet_order_line:read": "Read `hospitality.banquet_order_line` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.block_allocation:read": "Read `hospitality.block_allocation` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.board_sort_pattern:read": "Read `hospitality.board_sort_pattern` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.booking_origin:read": "Read `hospitality.booking_origin` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.brand:read": "Read `hospitality.brand` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.brand_operator_cost_entry:read": "Read `hospitality.brand_operator_cost_entry` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.business_date:read": "Read `hospitality.business_date` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.cancellation_policy:read": "Read `hospitality.cancellation_policy` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.cashier:read": "Read `hospitality.cashier` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.cashier_session:read": "Read `hospitality.cashier_session` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.cashier_transaction:read": "Read `hospitality.cashier_transaction` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.channel:read": "Read `hospitality.channel` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.channel_commission_period:read": "Read `hospitality.channel_commission_period` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.channel_connection:read": "Read `hospitality.channel_connection` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.channel_mapping:read": "Read `hospitality.channel_mapping` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.channel_mix_snapshot:read": "Read `hospitality.channel_mix_snapshot` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.channel_publication_run:read": "Read `hospitality.channel_publication_run` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.channel_reservation_delivery:read": "Read `hospitality.channel_reservation_delivery` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.charge:read": "Read `hospitality.charge` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.check_line:read": "Read `hospitality.check_line` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.check_payment:read": "Read `hospitality.check_payment` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.check_receipt:read": "Read `hospitality.check_receipt` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.checklist_result:read": "Read `hospitality.checklist_result` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.checklist_template:read": "Read `hospitality.checklist_template` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.checkpoint_result:read": "Read `hospitality.checkpoint_result` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.coaching_plan:read": "Read `hospitality.coaching_plan` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.commission_agreement:read": "Read `hospitality.commission_agreement` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.commission_detail:read": "Read `hospitality.commission_detail` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.commission_payment_batch:read": "Read `hospitality.commission_payment_batch` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.comp_authority_policy:read": "Read `hospitality.comp_authority_policy` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.company:read": "Read `hospitality.company` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.connector:read": "Read `hospitality.connector` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.connector_sync_run:read": "Read `hospitality.connector_sync_run` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.consent_policy:read": "Read `hospitality.consent_policy` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.currency_conversion_rate:read": "Read `hospitality.currency_conversion_rate` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.demand_forecast:read": "Read `hospitality.demand_forecast` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.deposit_policy:read": "Read `hospitality.deposit_policy` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.derived_rate:read": "Read `hospitality.derived_rate` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.design_dna:read": "Read `hospitality.design_dna` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.desk_session:read": "Read `hospitality.desk_session` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.development_pathway_definition:read": "Read `hospitality.development_pathway_definition` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.device:read": "Read `hospitality.device` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.dispute_evidence_packet:read": "Read `hospitality.dispute_evidence_packet` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.erasure_request:read": "Read `hospitality.erasure_request` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.external_consortium:read": "Read `hospitality.external_consortium` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.external_record_reference:read": "Read `hospitality.external_record_reference` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.fault_type:read": "Read `hospitality.fault_type` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.federated_analysis_definition:read": "Read `hospitality.federated_analysis_definition` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.federated_cohort_definition:read": "Read `hospitality.federated_cohort_definition` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.federated_contribution:read": "Read `hospitality.federated_contribution` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.federated_intelligence_program:read": "Read `hospitality.federated_intelligence_program` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.federated_output:read": "Read `hospitality.federated_output` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.federated_participation:read": "Read `hospitality.federated_participation` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.federated_run:read": "Read `hospitality.federated_run` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.feedback_label:read": "Read `hospitality.feedback_label` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.folio:read": "Read `hospitality.folio` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.folio_routing_rule:read": "Read `hospitality.folio_routing_rule` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.fraud_network_contribution:read": "Read `hospitality.fraud_network_contribution` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.fraud_network_signal:read": "Read `hospitality.fraud_network_signal` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.fraud_risk_assessment:read": "Read `hospitality.fraud_risk_assessment` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.function_event:read": "Read `hospitality.function_event` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.function_space:read": "Read `hospitality.function_space` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.grounding_scope:read": "Read `hospitality.grounding_scope` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.group_block:read": "Read `hospitality.group_block` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.group_displacement_analysis:read": "Read `hospitality.group_displacement_analysis` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.group_request:read": "Read `hospitality.group_request` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.guest_check:read": "Read `hospitality.guest_check` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.guest_conversation:read": "Read `hospitality.guest_conversation` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.guest_feedback:read": "Read `hospitality.guest_feedback` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.guest_feedback_entry:read": "Read `hospitality.guest_feedback_entry` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.guest_id_document:read": "Read `hospitality.guest_id_document` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.guest_message:read": "Read `hospitality.guest_message` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.housekeeping_briefing:read": "Read `hospitality.housekeeping_briefing` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.housekeeping_credit_rule:read": "Read `hospitality.housekeeping_credit_rule` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.housekeeping_task:read": "Read `hospitality.housekeeping_task` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.housekeeping_task_entry:read": "Read `hospitality.housekeeping_task_entry` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.incidental_hold_policy:read": "Read `hospitality.incidental_hold_policy` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.ingredient:read": "Read `hospitality.ingredient` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.ingredient_supplier_price:read": "Read `hospitality.ingredient_supplier_price` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.inspection_round:read": "Read `hospitality.inspection_round` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.invoice:read": "Read `hospitality.invoice` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.item_class:read": "Read `hospitality.item_class` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.item_price:read": "Read `hospitality.item_price` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.kitchen_ticket:read": "Read `hospitality.kitchen_ticket` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.labour_ledger_entry:read": "Read `hospitality.labour_ledger_entry` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.longevity_assessment:read": "Read `hospitality.longevity_assessment` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.lost_found_item:read": "Read `hospitality.lost_found_item` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.loyalty_program:read": "Read `hospitality.loyalty_program` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.maintenance_plan:read": "Read `hospitality.maintenance_plan` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.management_agreement:read": "Read `hospitality.management_agreement` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.material:read": "Read `hospitality.material` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.membership:read": "Read `hospitality.membership` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.membership_account:read": "Read `hospitality.membership_account` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.membership_initiation:read": "Read `hospitality.membership_initiation` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.membership_subscription:read": "Read `hospitality.membership_subscription` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.membership_tier:read": "Read `hospitality.membership_tier` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.menu:read": "Read `hospitality.menu` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.menu_item:read": "Read `hospitality.menu_item` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.menu_item_variant:read": "Read `hospitality.menu_item_variant` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.menu_section:read": "Read `hospitality.menu_section` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.merchant_account:read": "Read `hospitality.merchant_account` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.message_triage:read": "Read `hospitality.message_triage` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.metric_definition:read": "Read `hospitality.metric_definition` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.modifier_group:read": "Read `hospitality.modifier_group` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.modifier_option:read": "Read `hospitality.modifier_option` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.night_audit_run:read": "Read `hospitality.night_audit_run` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.no_show_posting_rule:read": "Read `hospitality.no_show_posting_rule` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.outlet:read": "Read `hospitality.outlet` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.owner_statement:read": "Read `hospitality.owner_statement` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.package:read": "Read `hospitality.package` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.package_component:read": "Read `hospitality.package_component` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.package_component_consumption:read": "Read `hospitality.package_component_consumption` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.package_sale:read": "Read `hospitality.package_sale` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.package_version:read": "Read `hospitality.package_version` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.participant_dispatch_attempt:read": "Read `hospitality.participant_dispatch_attempt` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.payment:read": "Read `hospitality.payment` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.payment_card:read": "Read `hospitality.payment_card` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.payment_dispute:read": "Read `hospitality.payment_dispute` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.payment_request:read": "Read `hospitality.payment_request` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.payout:read": "Read `hospitality.payout` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.payout_line:read": "Read `hospitality.payout_line` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.person:read": "Read `hospitality.person` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.person_merge_candidate:read": "Read `hospitality.person_merge_candidate` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.platform_ledger_line:read": "Read `hospitality.platform_ledger_line` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.portfolio:read": "Read `hospitality.portfolio` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.pre_shift_lineup_event:read": "Read `hospitality.pre_shift_lineup_event` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.prep_station:read": "Read `hospitality.prep_station` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.privacy_budget_account:read": "Read `hospitality.privacy_budget_account` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.privacy_budget_event:read": "Read `hospitality.privacy_budget_event` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.property:read": "Read `hospitality.property` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.property_budget:read": "Read `hospitality.property_budget` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.proposed_action:read": "Read `hospitality.proposed_action` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.public_area:read": "Read `hospitality.public_area` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.purpose_grant:read": "Read `hospitality.purpose_grant` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.rail_instruction:read": "Read `hospitality.rail_instruction` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.rate_per_night:read": "Read `hospitality.rate_per_night` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.rate_plan:read": "Read `hospitality.rate_plan` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.rate_recommendation:read": "Read `hospitality.rate_recommendation` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.rate_recommendation_run:read": "Read `hospitality.rate_recommendation_run` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.rate_restriction:read": "Read `hospitality.rate_restriction` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.recipe:read": "Read `hospitality.recipe` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.reciprocity_agreement:read": "Read `hospitality.reciprocity_agreement` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.recognition_event:read": "Read `hospitality.recognition_event` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.recovery_pattern_detection_run:read": "Read `hospitality.recovery_pattern_detection_run` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.recovery_toolkit:read": "Read `hospitality.recovery_toolkit` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.registration_card:read": "Read `hospitality.registration_card` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.reservation:read": "Read `hospitality.reservation` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.reservation_night:read": "Read `hospitality.reservation_night` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.reservation_room:read": "Read `hospitality.reservation_room` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.restriction_recommendation:read": "Read `hospitality.restriction_recommendation` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.retail_product:read": "Read `hospitality.retail_product` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.retail_product_line:read": "Read `hospitality.retail_product_line` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.room:read": "Read `hospitality.room` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.room_discrepancy:read": "Read `hospitality.room_discrepancy` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.room_queue_entry:read": "Read `hospitality.room_queue_entry` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.room_status_block:read": "Read `hospitality.room_status_block` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.room_type:read": "Read `hospitality.room_type` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.round_template:read": "Read `hospitality.round_template` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.sell_limit_recommendation:read": "Read `hospitality.sell_limit_recommendation` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.service_area:read": "Read `hospitality.service_area` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.service_item:read": "Read `hospitality.service_item` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.service_philosophy:read": "Read `hospitality.service_philosophy` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.service_recovery_event:read": "Read `hospitality.service_recovery_event` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.service_recovery_pattern:read": "Read `hospitality.service_recovery_pattern` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.service_register:read": "Read `hospitality.service_register` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.service_table:read": "Read `hospitality.service_table` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.share_group:read": "Read `hospitality.share_group` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.spa_service:read": "Read `hospitality.spa_service` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.staff_certification:read": "Read `hospitality.staff_certification` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.staff_employment_period:read": "Read `hospitality.staff_employment_period` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.staff_member:read": "Read `hospitality.staff_member` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.staff_shift:read": "Read `hospitality.staff_shift` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.stay:read": "Read `hospitality.stay` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.stay_offer:read": "Read `hospitality.stay_offer` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.stock_level:read": "Read `hospitality.stock_level` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.stock_movement:read": "Read `hospitality.stock_movement` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.stock_store:read": "Read `hospitality.stock_store` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.stored_object:read": "Read `hospitality.stored_object` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.tax_application:read": "Read `hospitality.tax_application` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.tax_exemption:read": "Read `hospitality.tax_exemption` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.tax_rule:read": "Read `hospitality.tax_rule` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.training_cohort:read": "Read `hospitality.training_cohort` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.treatment_room:read": "Read `hospitality.treatment_room` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.turnaway:read": "Read `hospitality.turnaway` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.utility_ledger_entry:read": "Read `hospitality.utility_ledger_entry` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.venue:read": "Read `hospitality.venue` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.venue_brand:read": "Read `hospitality.venue_brand` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.venue_visit:read": "Read `hospitality.venue_visit` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.waitlist_entry:read": "Read `hospitality.waitlist_entry` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.wellness_equipment:read": "Read `hospitality.wellness_equipment` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.wellness_modality:read": "Read `hospitality.wellness_modality` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.wellness_protocol:read": "Read `hospitality.wellness_protocol` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.work_order:read": "Read `hospitality.work_order` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.work_order_entry:read": "Read `hospitality.work_order_entry` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.worker_group:read": "Read `hospitality.worker_group` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.workflow_definition:read": "Read `hospitality.workflow_definition` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.workflow_run:read": "Read `hospitality.workflow_run` rows (and nothing else); the narrow form of `objects:read`.", "objects:hospitality.workflow_step_run:read": "Read `hospitality.workflow_step_run` rows (and nothing else); the narrow form of `objects:read`.", "objects:read": "Read objects, links, types, and events.", "objects:write": "Write binary attachments — initiate / finalize / delete on `/v1/attachments`, the one HTTP surface that writes object storage directly. Ordinary object & link mutation does NOT use this scope; it goes through typed actions on `/v1/actions/{action}/apply` (single-write-surface).", "tenant_admin:write": "Operator-privileged scope for whole-tenant lifecycle: per-tenant erasure and per-tenant export. A tenant token MUST NOT carry this — the scope is provisioned on operator principals, not tenant ones.", "webhooks:read": "Read webhook subscription state and delivery audit rows.", "webhooks:write": "Create, update, and delete webhook subscriptions; rotate and promote signing keys." }, "tokenUrl": "https://api.aerandil.com/oauth/token" } }, "type": "oauth2" }, "aerandil_webhook_signature": { "description": "HMAC-SHA256 signature attached to every outbound webhook delivery. Header value: `t=,v1=[,v1=]`. The signed payload is `\"{t}.{raw_body}\"`; receivers verify with constant-time comparison and SHOULD reject envelopes whose `t` is older than 5 minutes. During a key-rotation window the worker emits one `v1=` entry per active key. Unknown future chunks (e.g. `v2=`) MUST be ignored for forward-compat. \n\nModeled here as `apiKey` because OpenAPI 3.1 has no first-class HMAC type; the apiKey shape captures the transport (header) and lets generated SDK code render a receiver-side verification stub from the description.", "in": "header", "name": "Aerandil-Signature", "type": "apiKey" } } }, "info": { "contact": { "url": "https://github.com/aerandil-technologies/aerandil" }, "description": "Vendor-neutral hospitality ontology HTTP surface. Objects, links, actions, and events are exposed as a Foundry-style applyAction API plus typed CRUD routes; the OpenAPI 3.1 document at `/v1/openapi.json` is the machine-readable contract.", "license": { "identifier": "Apache-2.0", "name": "Apache-2.0" }, "title": "Aerandil API", "version": "0.0.1" }, "openapi": "3.1.0", "paths": { "/.well-known/jwks.json": { "get": { "description": "Publish the Ed25519 (EdDSA / OKP) public keys used to verify the bearer tokens `/oauth/token` issues (RFC 7517). \n\n**Public — no authentication.** Consumers cache the set and refetch only on an unknown `kid`; the short `max-age` keeps a rotated-out key from lingering in caches past the rotation grace window.", "operationId": "jwks", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "keys": { "items": { "type": "object" }, "type": "array" } }, "required": [ "keys" ], "type": "object" } } }, "description": "The active verification keys as a JWKS.", "headers": { "Cache-Control": { "description": "`public, max-age=300, must-revalidate`.", "schema": { "type": "string" } } } } }, "security": [], "summary": "Public JSON Web Key Set (token verification keys)", "tags": [ "oauth" ] } }, "/.well-known/oauth-authorization-server": { "get": { "description": "Discovery document for interactive OAuth 2.1 on this cell — the authorization, token and dynamic-registration endpoints, the scopes on offer, and the PKCE methods required.\n\n**Public — no authentication.** MCP clients MUST read this document (MCP `2025-06-18` §Server Metadata Discovery) after following the `resource_metadata` pointer on a `401` from the MCP endpoint. Returns `404` when the cell has no `AERANDIL_PUBLIC_BASE_URL`: every endpoint here is absolute, and deriving one from the request `Host` would let a caller point other clients at a host of their choosing.", "operationId": "oauthAuthorizationServerMetadata", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Authorization-server metadata." }, "404": { "description": "This cell publishes no metadata (no public base URL configured)." } }, "security": [], "summary": "Authorization-server metadata (RFC 8414)", "tags": [ "oauth" ] } }, "/oauth/register": { "post": { "description": "Obtain a `client_id` for an interactive OAuth 2.1 client — the way an MCP client (Claude, ChatGPT, n8n, Cursor) connects to this cell without anyone provisioning a credential for it.\n\n**Public — no authentication.** RFC 7591 §1.2 permits an open registration policy, and registering grants nothing: a fresh `client_id` can only ask a human to sign in, and the token that eventually results is capped by that person's role. Rate-limited per IP alongside `/oauth/token`.\n\nPublic clients only: `token_endpoint_auth_method` must be `none` and the client must use PKCE (`S256`). Redirect URIs are exact-matched at authorization time and must be `https:` or `http:` on a loopback address.", "operationId": "oauthRegisterClient", "requestBody": { "content": { "application/json": { "schema": { "properties": { "client_name": { "type": "string" }, "grant_types": { "items": { "enum": [ "authorization_code" ], "type": "string" }, "type": "array" }, "redirect_uris": { "description": "Exact redirect targets. `https:`, or `http:` on 127.0.0.1 / [::1] / localhost.", "items": { "type": "string" }, "type": "array" }, "response_types": { "items": { "enum": [ "code" ], "type": "string" }, "type": "array" }, "scope": { "type": "string" }, "software_id": { "type": "string" }, "software_version": { "type": "string" }, "token_endpoint_auth_method": { "enum": [ "none" ], "type": "string" } }, "required": [ "redirect_uris" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "client_id": { "type": "string" }, "client_id_issued_at": { "format": "int64", "type": "integer" }, "client_name": { "type": "string" }, "grant_types": { "items": { "type": "string" }, "type": "array" }, "redirect_uris": { "items": { "type": "string" }, "type": "array" }, "response_types": { "items": { "type": "string" }, "type": "array" }, "scope": { "type": "string" }, "token_endpoint_auth_method": { "type": "string" } }, "required": [ "client_id", "client_id_issued_at", "redirect_uris" ], "type": "object" } } }, "description": "The registered client." }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "type": "object" } } }, "description": "RFC 7591 §3.2.2 error — `invalid_redirect_uri` or `invalid_client_metadata`." } }, "security": [], "summary": "Register an OAuth client dynamically (RFC 7591)", "tags": [ "oauth" ] } }, "/oauth/token": { "post": { "description": "OAuth 2.1 `client_credentials` grant — exchange a `client_id` + `client_secret` for a short-lived bearer token whose `scopes` claim narrows the issued token to a subset of the client's pre-provisioned scopes. \n\n**Deviation from RFC 6749 §4.4.2.** Aerandil accepts the grant parameters as a JSON body (`application/json`), not the `application/x-www-form-urlencoded` body the RFC mandates. This is an explicit operational choice — every other Aerandil endpoint takes JSON, and SDK generators emit cleaner code for one wire format than two. Modern SaaS APIs (Stripe, Auth0 management API) have made the same call. RFC-conformant integrations generally fail open against a JSON token endpoint; if they don't, the integrator wraps a per-PMS shim. \n\nPublic endpoint — no bearer required. The HTTPS transport is the credential carrier; the request body is intentionally not authenticated by a prior token (that would be a chicken-and-egg).", "operationId": "aerandil_oauth_token", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } }, "description": "Token minted. `scope` is the granted set — intersection of the client's pre-provisioned scopes with the `scope` request parameter (when present)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authentication failed. Returned for unknown `client_id` and for `client_secret` mismatch alike — the two failure modes are deliberately indistinguishable to prevent client_id enumeration." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Request body invalid — unsupported `grant_type` (only `client_credentials` is accepted), malformed JSON, or unknown body fields." } }, "security": [], "summary": "Mint an access token", "tags": [ "oauth" ] } }, "/v1/action-types": { "get": { "description": "Schema-discovery surface for actions. Each entry surfaces the target object type, parameter count, and declared effects (create/modify/delete/link/modify_link/unlink) so a UI can render an action picker without walking `/v1/openapi.json`.", "operationId": "list_action_types", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "$ref": "#/components/schemas/ActionTypeSummary" }, "type": "array" }, "next_page_token": { "description": "Opaque cursor for the next page (AIP-158). Reserved for future growth; v1 returns `null` because the registry size is bounded.", "nullable": true, "type": "string" } }, "required": [ "data" ], "type": "object" } } }, "description": "Sorted summary list of every registered action type." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "List action types", "tags": [ "metadata" ] } }, "/v1/actions/hospitality.action.accept_waitlist_entry/apply": { "post": { "description": "Turn the wait into a booking. Replays the entry's request through `create_reservation` itself — not a bypass — so the full availability check, rate restrictions and stay bounds re-run at accept time against the house as it is *now*. The queue is never trusted: an entry offered this morning refuses this afternoon if the room went. The rate is re-decided here (`nightly_rate`, falling back to the entry's indicative `quoted_rate`; with neither, it refuses) because a rate quoted three weeks ago against a sold-out night is not a price the house still owns. An offered entry's held room-nights go back in the same transaction just before the create runs, so the room the offer kept is the room it books. On success the entry goes `accepted` and points at the reservation it became. Refuses an entry already accepted, cancelled, or expired.\n\nEffects: modify hospitality.waitlist_entry; link hospitality.link.waitlist_entry_became_reservation; create hospitality.reservation; create hospitality.reservation_room; create hospitality.reservation_night; link hospitality.link.reservation_for_property; link hospitality.link.reservation_for_guest; link hospitality.link.reservation_uses_rate_plan; link hospitality.link.reservation_for_room_type; link hospitality.link.reservation_has_room; link hospitality.link.reservation_room_for_room_type; link hospitality.link.reservation_room_has_night; link hospitality.link.reservation_night_uses_rate_plan; modify hospitality.availability_day.", "operationId": "apply_hospitality_action_accept_waitlist_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "booked_at": { "format": "date-time", "title": "Booking instant (defaults to now)", "type": "string" }, "guarantee": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "title": "Guarantee the booking is taken under (defaults to deposit where the house's deposit policy covers the booking, else none)", "type": "string" }, "market_segment": { "enum": [ "transient", "group", "contract" ], "title": "Demand segment", "type": "string" }, "nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Rate for the booking (defaults to the entry's quoted_rate)", "type": "object" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "Booking channel (defaults to direct_web)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.waitlist_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.waitlist_entry_became_reservation", "hospitality.link.reservation_for_property", "hospitality.link.reservation_for_guest", "hospitality.link.reservation_uses_rate_plan", "hospitality.link.reservation_for_room_type", "hospitality.link.reservation_has_room", "hospitality.link.reservation_room_for_room_type", "hospitality.link.reservation_room_has_night", "hospitality.link.reservation_night_uses_rate_plan" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.waitlist_entry", "hospitality.reservation", "hospitality.reservation_room", "hospitality.reservation_night", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.accept_waitlist_entry:apply" ] } ], "summary": "Accept waitlist entry", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.accept_waitlist_entry/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_accept_waitlist_entry` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.accept_waitlist_entry:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_accept_waitlist_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "booked_at": { "format": "date-time", "title": "Booking instant (defaults to now)", "type": "string" }, "guarantee": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "title": "Guarantee the booking is taken under (defaults to deposit where the house's deposit policy covers the booking, else none)", "type": "string" }, "market_segment": { "enum": [ "transient", "group", "contract" ], "title": "Demand segment", "type": "string" }, "nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Rate for the booking (defaults to the entry's quoted_rate)", "type": "object" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "Booking channel (defaults to direct_web)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.waitlist_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.waitlist_entry_became_reservation", "hospitality.link.reservation_for_property", "hospitality.link.reservation_for_guest", "hospitality.link.reservation_uses_rate_plan", "hospitality.link.reservation_for_room_type", "hospitality.link.reservation_has_room", "hospitality.link.reservation_room_for_room_type", "hospitality.link.reservation_room_has_night", "hospitality.link.reservation_night_uses_rate_plan" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.waitlist_entry", "hospitality.reservation", "hospitality.reservation_room", "hospitality.reservation_night", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Accept waitlist entry (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.accept_waitlist_entry/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_accept_waitlist_entry`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_accept_waitlist_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "booked_at": { "format": "date-time", "title": "Booking instant (defaults to now)", "type": "string" }, "guarantee": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "title": "Guarantee the booking is taken under (defaults to deposit where the house's deposit policy covers the booking, else none)", "type": "string" }, "market_segment": { "enum": [ "transient", "group", "contract" ], "title": "Demand segment", "type": "string" }, "nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Rate for the booking (defaults to the entry's quoted_rate)", "type": "object" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "Booking channel (defaults to direct_web)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.waitlist_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Accept waitlist entry (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.accept_waitlist_entry/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_accept_waitlist_entry` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.accept_waitlist_entry:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_accept_waitlist_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "booked_at": { "format": "date-time", "title": "Booking instant (defaults to now)", "type": "string" }, "guarantee": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "title": "Guarantee the booking is taken under (defaults to deposit where the house's deposit policy covers the booking, else none)", "type": "string" }, "market_segment": { "enum": [ "transient", "group", "contract" ], "title": "Demand segment", "type": "string" }, "nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Rate for the booking (defaults to the entry's quoted_rate)", "type": "object" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "Booking channel (defaults to direct_web)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.waitlist_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Accept waitlist entry (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.acknowledge_channel_reservation/apply": { "post": { "description": "Record that our acknowledgement reached the partner, closing the at-least-once loop. Acknowledgement is a timestamp rather than a state because it composes with both outcomes: the partner is told the message was handled whether we applied it or refused it, and only silence triggers redelivery. A delivery still `received` or `failed` cannot be acknowledged — that is precisely the case where we want the partner to send it again. Emits `channel_reservation.acknowledged`.\n\nEffects: modify hospitality.channel_reservation_delivery.", "operationId": "apply_hospitality_action_acknowledge_channel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_reservation_delivery" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.channel_reservation_delivery" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.acknowledge_channel_reservation:apply" ] } ], "summary": "Acknowledge channel reservation", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.acknowledge_channel_reservation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_acknowledge_channel_reservation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.acknowledge_channel_reservation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_acknowledge_channel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_reservation_delivery" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.channel_reservation_delivery" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Acknowledge channel reservation (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.acknowledge_channel_reservation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_acknowledge_channel_reservation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_acknowledge_channel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_reservation_delivery" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Acknowledge channel reservation (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.acknowledge_channel_reservation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_acknowledge_channel_reservation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.acknowledge_channel_reservation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_acknowledge_channel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_reservation_delivery" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Acknowledge channel reservation (rollup delta)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.activate_automation/apply": { "post": { "description": "Enable a `draft` or `paused` automation — the evaluator starts matching its condition and firing its effect. Idempotent on an already-active automation; refused on an `archived` one. Emits `automation.activated`.\n\nEffects: modify hospitality.automation.", "operationId": "apply_hospitality_action_activate_automation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.automation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.automation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.activate_automation:apply" ] } ], "summary": "Activate automation", "tags": [ "automation" ] } }, "/v1/actions/hospitality.action.activate_automation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_activate_automation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.activate_automation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_activate_automation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.automation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.automation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Activate automation (dry-run)", "tags": [ "automation" ] } }, "/v1/actions/hospitality.action.activate_automation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_activate_automation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_activate_automation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.automation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Activate automation (dry-run)", "tags": [ "automation" ] } }, "/v1/actions/hospitality.action.activate_automation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_activate_automation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.activate_automation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_activate_automation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.automation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Activate automation (rollup delta)", "tags": [ "automation" ] } }, "/v1/actions/hospitality.action.add_banquet_order_line/apply": { "post": { "description": "Add a resource to the order — a menu per person, a screen at a fixed quantity — in the order's currency. Adding to an issued order marks it `revised`, so the departments get it again; a posted or cancelled order refuses.\n\nEffects: create hospitality.banquet_order_line; modify hospitality.banquet_event_order; link hospitality.link.banquet_order_has_line; link hospitality.link.banquet_order_line_for_service_item.", "operationId": "apply_hospitality_action_add_banquet_order_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "category": { "enum": [ "room_rental", "food", "beverage", "audio_visual", "equipment", "labour", "decor", "entertainment", "other" ], "title": "Section of the sheet", "type": "string" }, "description": { "title": "What the line is", "type": "string" }, "notes": { "title": "Line notes", "type": "string" }, "quantity": { "title": "Fixed quantity, or units per person (default 1)", "type": "integer" }, "quantity_basis": { "enum": [ "per_person", "fixed" ], "title": "per_person or fixed", "type": "string" }, "sequence": { "title": "Position on the sheet (default: after the last line)", "type": "integer" }, "serve_at": { "format": "date-time", "title": "When the line is served or set", "type": "string" }, "service_item_id": { "format": "uuid", "title": "The catalogue item behind the line", "type": "string", "x-aerandil-references": "hospitality.service_item" }, "unit_price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Price per unit, in the order's currency", "type": "object" } }, "required": [ "category", "description", "quantity_basis", "unit_price" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_event_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.banquet_order_has_line", "hospitality.link.banquet_order_line_for_service_item" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.banquet_order_line", "hospitality.banquet_event_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.add_banquet_order_line:apply" ] } ], "summary": "Add banquet order line", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.add_banquet_order_line/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_add_banquet_order_line` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.add_banquet_order_line:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_add_banquet_order_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "category": { "enum": [ "room_rental", "food", "beverage", "audio_visual", "equipment", "labour", "decor", "entertainment", "other" ], "title": "Section of the sheet", "type": "string" }, "description": { "title": "What the line is", "type": "string" }, "notes": { "title": "Line notes", "type": "string" }, "quantity": { "title": "Fixed quantity, or units per person (default 1)", "type": "integer" }, "quantity_basis": { "enum": [ "per_person", "fixed" ], "title": "per_person or fixed", "type": "string" }, "sequence": { "title": "Position on the sheet (default: after the last line)", "type": "integer" }, "serve_at": { "format": "date-time", "title": "When the line is served or set", "type": "string" }, "service_item_id": { "format": "uuid", "title": "The catalogue item behind the line", "type": "string", "x-aerandil-references": "hospitality.service_item" }, "unit_price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Price per unit, in the order's currency", "type": "object" } }, "required": [ "category", "description", "quantity_basis", "unit_price" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_event_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.banquet_order_has_line", "hospitality.link.banquet_order_line_for_service_item" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.banquet_order_line", "hospitality.banquet_event_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Add banquet order line (dry-run)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.add_banquet_order_line/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_add_banquet_order_line`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_add_banquet_order_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "category": { "enum": [ "room_rental", "food", "beverage", "audio_visual", "equipment", "labour", "decor", "entertainment", "other" ], "title": "Section of the sheet", "type": "string" }, "description": { "title": "What the line is", "type": "string" }, "notes": { "title": "Line notes", "type": "string" }, "quantity": { "title": "Fixed quantity, or units per person (default 1)", "type": "integer" }, "quantity_basis": { "enum": [ "per_person", "fixed" ], "title": "per_person or fixed", "type": "string" }, "sequence": { "title": "Position on the sheet (default: after the last line)", "type": "integer" }, "serve_at": { "format": "date-time", "title": "When the line is served or set", "type": "string" }, "service_item_id": { "format": "uuid", "title": "The catalogue item behind the line", "type": "string", "x-aerandil-references": "hospitality.service_item" }, "unit_price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Price per unit, in the order's currency", "type": "object" } }, "required": [ "category", "description", "quantity_basis", "unit_price" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_event_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Add banquet order line (dry-run)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.add_banquet_order_line/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_add_banquet_order_line` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.add_banquet_order_line:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_add_banquet_order_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "category": { "enum": [ "room_rental", "food", "beverage", "audio_visual", "equipment", "labour", "decor", "entertainment", "other" ], "title": "Section of the sheet", "type": "string" }, "description": { "title": "What the line is", "type": "string" }, "notes": { "title": "Line notes", "type": "string" }, "quantity": { "title": "Fixed quantity, or units per person (default 1)", "type": "integer" }, "quantity_basis": { "enum": [ "per_person", "fixed" ], "title": "per_person or fixed", "type": "string" }, "sequence": { "title": "Position on the sheet (default: after the last line)", "type": "integer" }, "serve_at": { "format": "date-time", "title": "When the line is served or set", "type": "string" }, "service_item_id": { "format": "uuid", "title": "The catalogue item behind the line", "type": "string", "x-aerandil-references": "hospitality.service_item" }, "unit_price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Price per unit, in the order's currency", "type": "object" } }, "required": [ "category", "description", "quantity_basis", "unit_price" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_event_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Add banquet order line (rollup delta)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.add_check_line/apply": { "post": { "description": "Order one item onto an open check. The line rings a variant — the one named, else the item's only or default variant — at the most specific `item_price` in force for the check's outlet, order kind and daypart on the check's business date, and snapshots that price, the item class's revenue category and the VAT: every tax rule in force for the class (its takeaway class off the premises), rounded per rule to the penny half away from zero, never down. An item with no class, no price in force, two equally specific prices, or a tax class with no rule refuses to ring. The snapshot is the financial record, so menu and rate edits never rewrite a rung sale. Course defaults to the item's `course_default`, then its class's, then 1. `modifiers` are the options chosen, each from a group the item uses: every group's bounds hold (the item's own override on the link beats the group's), and a required group (min above zero) must be answered. An option that adds a variant rings as its own line under this one (check_line_modifies_line) — at the option's price, else the variant's own, free under the `no` prefix — with that item's VAT and revenue category, quantity times this line's; an option with no variant, and any no / light / side prefix, joins this line's kitchen `instructions`. A present `fulfilled_at` lands the line already delivered, for feeds that record completed service rather than drive it (a POS export's lines carry no kitchen lifecycle to replay); live ordering omits it and the line lands `entered` for `fire_course` to pick up. A present `external_ref` routes the create through the `check_line_external_ref` business key, making a crashed-pass retry a replay instead of a duplicate line. The check's totals move with the line. Emits `fnb.line_added` for the line and each modifier line.\n\nEffects: create hospitality.check_line; link hospitality.link.check_line_on_check; link hospitality.link.check_line_for_menu_item; link hospitality.link.check_line_for_variant; link hospitality.link.check_line_modifies_line; modify hospitality.guest_check.", "operationId": "apply_hospitality_action_add_check_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "course_number": { "title": "Course (defaults to the item's course_default, then its class's, then 1)", "type": "integer" }, "external_ref": { "title": "Source-system key for replayed / connector-landed lines (replay key)", "type": "string" }, "fulfilled_at": { "format": "date-time", "title": "When service completed — lands the line already fulfilled (replayed / connector-landed histories; live ordering omits it)", "type": "string" }, "menu_item_id": { "format": "uuid", "title": "Menu item ordered", "type": "string", "x-aerandil-references": "hospitality.menu_item" }, "modifiers": { "items": { "properties": { "option_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.modifier_option" }, "prefix": { "enum": [ "no", "extra", "light", "side" ], "type": "string" }, "quantity": { "type": "integer" } }, "required": [ "option_id" ], "type": "object" }, "title": "Options chosen: each an option_id from a group the item uses, an optional prefix (no / extra / light / side) and quantity (default 1)", "type": "array" }, "notes": { "title": "Kitchen-facing note", "type": "string" }, "quantity": { "title": "Quantity (default 1)", "type": "integer" }, "seat_number": { "title": "Seat the item is for (1–99)", "type": "integer" }, "variant_id": { "format": "uuid", "title": "Variant ordered (the 175 ml, the bottle) — omit for the item's only or default variant", "type": "string", "x-aerandil-references": "hospitality.menu_item_variant" } }, "required": [ "menu_item_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.check_line_on_check", "hospitality.link.check_line_for_menu_item", "hospitality.link.check_line_for_variant", "hospitality.link.check_line_modifies_line" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.check_line", "hospitality.guest_check" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.add_check_line:apply" ] } ], "summary": "Add check line", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.add_check_line/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_add_check_line` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.add_check_line:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_add_check_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "course_number": { "title": "Course (defaults to the item's course_default, then its class's, then 1)", "type": "integer" }, "external_ref": { "title": "Source-system key for replayed / connector-landed lines (replay key)", "type": "string" }, "fulfilled_at": { "format": "date-time", "title": "When service completed — lands the line already fulfilled (replayed / connector-landed histories; live ordering omits it)", "type": "string" }, "menu_item_id": { "format": "uuid", "title": "Menu item ordered", "type": "string", "x-aerandil-references": "hospitality.menu_item" }, "modifiers": { "items": { "properties": { "option_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.modifier_option" }, "prefix": { "enum": [ "no", "extra", "light", "side" ], "type": "string" }, "quantity": { "type": "integer" } }, "required": [ "option_id" ], "type": "object" }, "title": "Options chosen: each an option_id from a group the item uses, an optional prefix (no / extra / light / side) and quantity (default 1)", "type": "array" }, "notes": { "title": "Kitchen-facing note", "type": "string" }, "quantity": { "title": "Quantity (default 1)", "type": "integer" }, "seat_number": { "title": "Seat the item is for (1–99)", "type": "integer" }, "variant_id": { "format": "uuid", "title": "Variant ordered (the 175 ml, the bottle) — omit for the item's only or default variant", "type": "string", "x-aerandil-references": "hospitality.menu_item_variant" } }, "required": [ "menu_item_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.check_line_on_check", "hospitality.link.check_line_for_menu_item", "hospitality.link.check_line_for_variant", "hospitality.link.check_line_modifies_line" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.check_line", "hospitality.guest_check" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Add check line (dry-run)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.add_check_line/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_add_check_line`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_add_check_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "course_number": { "title": "Course (defaults to the item's course_default, then its class's, then 1)", "type": "integer" }, "external_ref": { "title": "Source-system key for replayed / connector-landed lines (replay key)", "type": "string" }, "fulfilled_at": { "format": "date-time", "title": "When service completed — lands the line already fulfilled (replayed / connector-landed histories; live ordering omits it)", "type": "string" }, "menu_item_id": { "format": "uuid", "title": "Menu item ordered", "type": "string", "x-aerandil-references": "hospitality.menu_item" }, "modifiers": { "items": { "properties": { "option_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.modifier_option" }, "prefix": { "enum": [ "no", "extra", "light", "side" ], "type": "string" }, "quantity": { "type": "integer" } }, "required": [ "option_id" ], "type": "object" }, "title": "Options chosen: each an option_id from a group the item uses, an optional prefix (no / extra / light / side) and quantity (default 1)", "type": "array" }, "notes": { "title": "Kitchen-facing note", "type": "string" }, "quantity": { "title": "Quantity (default 1)", "type": "integer" }, "seat_number": { "title": "Seat the item is for (1–99)", "type": "integer" }, "variant_id": { "format": "uuid", "title": "Variant ordered (the 175 ml, the bottle) — omit for the item's only or default variant", "type": "string", "x-aerandil-references": "hospitality.menu_item_variant" } }, "required": [ "menu_item_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Add check line (dry-run)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.add_check_line/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_add_check_line` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.add_check_line:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_add_check_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "course_number": { "title": "Course (defaults to the item's course_default, then its class's, then 1)", "type": "integer" }, "external_ref": { "title": "Source-system key for replayed / connector-landed lines (replay key)", "type": "string" }, "fulfilled_at": { "format": "date-time", "title": "When service completed — lands the line already fulfilled (replayed / connector-landed histories; live ordering omits it)", "type": "string" }, "menu_item_id": { "format": "uuid", "title": "Menu item ordered", "type": "string", "x-aerandil-references": "hospitality.menu_item" }, "modifiers": { "items": { "properties": { "option_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.modifier_option" }, "prefix": { "enum": [ "no", "extra", "light", "side" ], "type": "string" }, "quantity": { "type": "integer" } }, "required": [ "option_id" ], "type": "object" }, "title": "Options chosen: each an option_id from a group the item uses, an optional prefix (no / extra / light / side) and quantity (default 1)", "type": "array" }, "notes": { "title": "Kitchen-facing note", "type": "string" }, "quantity": { "title": "Quantity (default 1)", "type": "integer" }, "seat_number": { "title": "Seat the item is for (1–99)", "type": "integer" }, "variant_id": { "format": "uuid", "title": "Variant ordered (the 175 ml, the bottle) — omit for the item's only or default variant", "type": "string", "x-aerandil-references": "hospitality.menu_item_variant" } }, "required": [ "menu_item_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Add check line (rollup delta)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.add_check_payment/apply": { "post": { "description": "Take one tender against an open check — the kernel is the system of record for a check's payments. `amount` is what the payment applies to the check and may not exceed `balance_due`, except in cash: cash `tendered` (default `amount`) above the balance applies the balance and gives the rest back as `change_given`. A `tip` rides only on card, room_charge and charge_to_key and stays out of `paid_total`. A card payment carries the terminal's references (`psp_reference`, `terminal_transaction_id`, `poiid`), never card data. A folio tender is bound server-side, the same on every path: room_charge requires `folio_id` and `reservation_id`, and the folio must be an open guest window of that booking's in-house stay at the check's own property (a house, master or company account, another booking's bill or another hotel's is refused); charge_to_key requires `credential_token`, the tapped key, resolved as `post_charge_by_credential` resolves it — its in-house stay names the folio and the reservation (a client `folio_id` or `reservation_id` that is not the key's is refused) and its per-charge and daily caps bound the payment and its tip; a tap is live, so a `paid_at` more than five minutes from the kernel's clock is refused and its postings are dated when the kernel records them, the clock the daily cap counts by. `guest_id`, the guest the server confirmed, must be the reservation's guest (a sharer signs on their own booking); it is recorded on the payment and on each folio charge as `signed_by`. They post to that open folio as the payment is taken: one charge per revenue category on the check (bucket = the outlet's usali_department, `charge_at_outlet`, `revenue_category`, its share of the VAT as tax applications), apportioned by largest remainder so the parts sum to the payment exactly, and the tip as a separate `gratuity` charge — a pass-through, never revenue — each emitting `charge.posted.recorded`, the payment linked to the charges and the check to the folio. The stay's package allowance is consumed with no prompt and no other tender: when the folio's in-house stay holds a live package component with a `daypart` — the check's own meal period, else an `all_day` credit — due on the check's business date (a breakfast the morning after its night), eaten at this outlet (an alternate outlet, or any when it names none) and with something left, it covers the payment's food and soft-drink shares up to what is left (never alcohol, never the tip): that part is recorded as the payment's `allowance_applied` and as a `package_component_consumption` (allowance and consumed both the amount, `consumed`, with the check's covers) through the one package write, linked to the payment (`consumption_for_check_payment`), whose balance-neutral package line on the folio is one of the payment's postings — and only the rest posts as the charges the guest owes, the covered shares shrunk with their VAT. One component per payment. Every payment records its share of each category and its VAT (`allocation`) over what earlier payments left, so a check paid in parts sums exactly. The payment that brings `balance_due` to zero settles the check — every line must be fulfilled, voided or comped by then — stamping `settled_at` (= `paid_at`), marking a seated table dirty and emitting `fnb.check_settled` with the per-tender breakdown. Business time: `paid_at` defaults to now. A present `external_ref` routes the create through the `check_payment_external_ref` business key, so a replayed payment is a no-op rather than a second payment. A room charge or charge-to-key is held to the stay's posting rules (`set_posting_rules`): a no-post stay refuses it (`no_post: …`), and so does one whose credit — the greater of its credit limit and its live card holds, less its bills' balance and the room still due — the posting and its tip would pass (`no_credit: …`). An override (`override_reason`) taken under a manager's own session lets the refusal through — an override is proven by who is signed in, not by who is named: the authoriser recorded on the payment (`override_kind`, `authorised_by`, `override_reason`) and emitted as `fnb.posting_override` is the session's staff member, and a body `authorised_by` must be that same one (`override_not_authenticated: …`). An override with nothing to override is refused (`nothing_to_override: …`), as is one under a session that is no manager's (`not_a_manager: …`) or none at all (`override_not_authenticated: …`). Emits `fnb.payment_added`.\n\nEffects: create hospitality.check_payment; link hospitality.link.check_payment_on_check; link hospitality.link.check_payment_to_folio; modify hospitality.guest_check; create hospitality.charge; create hospitality.tax_application; link hospitality.link.folio_has_charge; link hospitality.link.charge_at_outlet; link hospitality.link.charge_has_tax_application; link hospitality.link.check_payment_posted_charge; link hospitality.link.check_settled_to_folio; link hospitality.link.charge_via_credential; modify hospitality.folio; modify hospitality.service_table; create hospitality.check_receipt; link hospitality.link.receipt_for_check; create hospitality.package_component_consumption; modify hospitality.package_sale; link hospitality.link.package_sale_has_consumption; link hospitality.link.consumption_for_charge; link hospitality.link.charge_attributed_to_package_sale; link hospitality.link.charge_attributed_to_package_component; link hospitality.link.consumption_for_check_payment.", "operationId": "apply_hospitality_action_add_check_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Applied to the check (tip excluded); cash may exceed the balance and gives change", "type": "object" }, "authorised_by": { "format": "uuid", "title": "Confirms the overriding manager (optional; with override_reason): must be the staff member signed in — the override's authoriser is always the session's own, never one named here", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "credential_token": { "title": "The tapped room key's token (required for charge_to_key) — resolved server-side to its in-house stay and folio", "type": "string" }, "external_ref": { "title": "Source-system key for a replayed / connector-landed payment (replay key)", "type": "string" }, "folio_id": { "format": "uuid", "title": "Folio to post to (required for room_charge; for charge_to_key the key names it, and any other is refused)", "type": "string", "x-aerandil-references": "hospitality.folio" }, "guest_id": { "format": "uuid", "title": "The guest the server confirmed — the reservation's guest (room_charge and charge_to_key)", "type": "string", "x-aerandil-references": "hospitality.person" }, "override_reason": { "title": "Override the stay's no-post or credit refusal, and why (room_charge and charge_to_key) — taken under a manager's own session: an F&B manager, a front-office supervisor, the manager on duty, the general manager or the owner, active at the check's house", "type": "string" }, "paid_at": { "format": "date-time", "title": "When the payment was taken — business time (defaults to now)", "type": "string" }, "poiid": { "title": "The terminal (POIID) a card payment was taken on", "type": "string" }, "psp_reference": { "title": "The processor's reference for a card payment (Adyen pspReference)", "type": "string" }, "reservation_id": { "format": "uuid", "title": "The reservation the folio is a window of (required for room_charge; for charge_to_key the key names it)", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "tender": { "enum": [ "room_charge", "cash", "card", "comp", "external", "charge_to_key" ], "title": "Tender", "type": "string" }, "tendered": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Cash handed over (cash only; defaults to amount)", "type": "object" }, "terminal_transaction_id": { "title": "The terminal's own transaction id for a card payment", "type": "string" }, "tip": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Tip (card, room_charge and charge_to_key only)", "type": "object" } }, "required": [ "tender", "amount" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.check_payment_on_check", "hospitality.link.check_payment_to_folio", "hospitality.link.folio_has_charge", "hospitality.link.charge_at_outlet", "hospitality.link.charge_has_tax_application", "hospitality.link.check_payment_posted_charge", "hospitality.link.check_settled_to_folio", "hospitality.link.charge_via_credential", "hospitality.link.receipt_for_check", "hospitality.link.package_sale_has_consumption", "hospitality.link.consumption_for_charge", "hospitality.link.charge_attributed_to_package_sale", "hospitality.link.charge_attributed_to_package_component", "hospitality.link.consumption_for_check_payment" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.check_payment", "hospitality.guest_check", "hospitality.charge", "hospitality.tax_application", "hospitality.folio", "hospitality.service_table", "hospitality.check_receipt", "hospitality.package_component_consumption", "hospitality.package_sale" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.add_check_payment:apply" ] } ], "summary": "Add check payment", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.add_check_payment/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_add_check_payment` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.add_check_payment:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_add_check_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Applied to the check (tip excluded); cash may exceed the balance and gives change", "type": "object" }, "authorised_by": { "format": "uuid", "title": "Confirms the overriding manager (optional; with override_reason): must be the staff member signed in — the override's authoriser is always the session's own, never one named here", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "credential_token": { "title": "The tapped room key's token (required for charge_to_key) — resolved server-side to its in-house stay and folio", "type": "string" }, "external_ref": { "title": "Source-system key for a replayed / connector-landed payment (replay key)", "type": "string" }, "folio_id": { "format": "uuid", "title": "Folio to post to (required for room_charge; for charge_to_key the key names it, and any other is refused)", "type": "string", "x-aerandil-references": "hospitality.folio" }, "guest_id": { "format": "uuid", "title": "The guest the server confirmed — the reservation's guest (room_charge and charge_to_key)", "type": "string", "x-aerandil-references": "hospitality.person" }, "override_reason": { "title": "Override the stay's no-post or credit refusal, and why (room_charge and charge_to_key) — taken under a manager's own session: an F&B manager, a front-office supervisor, the manager on duty, the general manager or the owner, active at the check's house", "type": "string" }, "paid_at": { "format": "date-time", "title": "When the payment was taken — business time (defaults to now)", "type": "string" }, "poiid": { "title": "The terminal (POIID) a card payment was taken on", "type": "string" }, "psp_reference": { "title": "The processor's reference for a card payment (Adyen pspReference)", "type": "string" }, "reservation_id": { "format": "uuid", "title": "The reservation the folio is a window of (required for room_charge; for charge_to_key the key names it)", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "tender": { "enum": [ "room_charge", "cash", "card", "comp", "external", "charge_to_key" ], "title": "Tender", "type": "string" }, "tendered": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Cash handed over (cash only; defaults to amount)", "type": "object" }, "terminal_transaction_id": { "title": "The terminal's own transaction id for a card payment", "type": "string" }, "tip": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Tip (card, room_charge and charge_to_key only)", "type": "object" } }, "required": [ "tender", "amount" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.check_payment_on_check", "hospitality.link.check_payment_to_folio", "hospitality.link.folio_has_charge", "hospitality.link.charge_at_outlet", "hospitality.link.charge_has_tax_application", "hospitality.link.check_payment_posted_charge", "hospitality.link.check_settled_to_folio", "hospitality.link.charge_via_credential", "hospitality.link.receipt_for_check", "hospitality.link.package_sale_has_consumption", "hospitality.link.consumption_for_charge", "hospitality.link.charge_attributed_to_package_sale", "hospitality.link.charge_attributed_to_package_component", "hospitality.link.consumption_for_check_payment" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.check_payment", "hospitality.guest_check", "hospitality.charge", "hospitality.tax_application", "hospitality.folio", "hospitality.service_table", "hospitality.check_receipt", "hospitality.package_component_consumption", "hospitality.package_sale" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Add check payment (dry-run)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.add_check_payment/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_add_check_payment`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_add_check_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Applied to the check (tip excluded); cash may exceed the balance and gives change", "type": "object" }, "authorised_by": { "format": "uuid", "title": "Confirms the overriding manager (optional; with override_reason): must be the staff member signed in — the override's authoriser is always the session's own, never one named here", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "credential_token": { "title": "The tapped room key's token (required for charge_to_key) — resolved server-side to its in-house stay and folio", "type": "string" }, "external_ref": { "title": "Source-system key for a replayed / connector-landed payment (replay key)", "type": "string" }, "folio_id": { "format": "uuid", "title": "Folio to post to (required for room_charge; for charge_to_key the key names it, and any other is refused)", "type": "string", "x-aerandil-references": "hospitality.folio" }, "guest_id": { "format": "uuid", "title": "The guest the server confirmed — the reservation's guest (room_charge and charge_to_key)", "type": "string", "x-aerandil-references": "hospitality.person" }, "override_reason": { "title": "Override the stay's no-post or credit refusal, and why (room_charge and charge_to_key) — taken under a manager's own session: an F&B manager, a front-office supervisor, the manager on duty, the general manager or the owner, active at the check's house", "type": "string" }, "paid_at": { "format": "date-time", "title": "When the payment was taken — business time (defaults to now)", "type": "string" }, "poiid": { "title": "The terminal (POIID) a card payment was taken on", "type": "string" }, "psp_reference": { "title": "The processor's reference for a card payment (Adyen pspReference)", "type": "string" }, "reservation_id": { "format": "uuid", "title": "The reservation the folio is a window of (required for room_charge; for charge_to_key the key names it)", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "tender": { "enum": [ "room_charge", "cash", "card", "comp", "external", "charge_to_key" ], "title": "Tender", "type": "string" }, "tendered": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Cash handed over (cash only; defaults to amount)", "type": "object" }, "terminal_transaction_id": { "title": "The terminal's own transaction id for a card payment", "type": "string" }, "tip": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Tip (card, room_charge and charge_to_key only)", "type": "object" } }, "required": [ "tender", "amount" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Add check payment (dry-run)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.add_check_payment/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_add_check_payment` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.add_check_payment:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_add_check_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Applied to the check (tip excluded); cash may exceed the balance and gives change", "type": "object" }, "authorised_by": { "format": "uuid", "title": "Confirms the overriding manager (optional; with override_reason): must be the staff member signed in — the override's authoriser is always the session's own, never one named here", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "credential_token": { "title": "The tapped room key's token (required for charge_to_key) — resolved server-side to its in-house stay and folio", "type": "string" }, "external_ref": { "title": "Source-system key for a replayed / connector-landed payment (replay key)", "type": "string" }, "folio_id": { "format": "uuid", "title": "Folio to post to (required for room_charge; for charge_to_key the key names it, and any other is refused)", "type": "string", "x-aerandil-references": "hospitality.folio" }, "guest_id": { "format": "uuid", "title": "The guest the server confirmed — the reservation's guest (room_charge and charge_to_key)", "type": "string", "x-aerandil-references": "hospitality.person" }, "override_reason": { "title": "Override the stay's no-post or credit refusal, and why (room_charge and charge_to_key) — taken under a manager's own session: an F&B manager, a front-office supervisor, the manager on duty, the general manager or the owner, active at the check's house", "type": "string" }, "paid_at": { "format": "date-time", "title": "When the payment was taken — business time (defaults to now)", "type": "string" }, "poiid": { "title": "The terminal (POIID) a card payment was taken on", "type": "string" }, "psp_reference": { "title": "The processor's reference for a card payment (Adyen pspReference)", "type": "string" }, "reservation_id": { "format": "uuid", "title": "The reservation the folio is a window of (required for room_charge; for charge_to_key the key names it)", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "tender": { "enum": [ "room_charge", "cash", "card", "comp", "external", "charge_to_key" ], "title": "Tender", "type": "string" }, "tendered": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Cash handed over (cash only; defaults to amount)", "type": "object" }, "terminal_transaction_id": { "title": "The terminal's own transaction id for a card payment", "type": "string" }, "tip": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Tip (card, room_charge and charge_to_key only)", "type": "object" } }, "required": [ "tender", "amount" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Add check payment (rollup delta)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.add_dependent_membership/apply": { "post": { "description": "Mint a dependent `membership` row under the target account. The Aman Founders registered-companions case and the Saint Haven / Equinox Hotel spouse+child shape both use this action. Dependency validation (Aman Founders cap of four registered members per account; family-rate pricing tier on the existing subscription) lives in the handler.\n\nEffects: create hospitality.membership; link hospitality.link.membership_account_has_membership; link hospitality.link.membership_for_person; link hospitality.link.membership_at_tier.", "operationId": "apply_hospitality_action_add_dependent_membership", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "dependency_kind": { "enum": [ "primary", "spouse", "child", "registered_member", "transferred_legacy" ], "title": "Dependency kind (spouse / child / registered_member)", "type": "string" }, "effective_from": { "format": "date-time", "title": "Tier attachment start", "type": "string" }, "person_id": { "format": "uuid", "title": "Dependent person (typed reference)", "type": "string", "x-aerandil-references": "hospitality.person" }, "tier_id": { "format": "uuid", "title": "Tier attachment for the dependent", "type": "string", "x-aerandil-references": "hospitality.membership_tier" } }, "required": [ "dependency_kind", "tier_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership_account" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.membership_account_has_membership", "hospitality.link.membership_for_person", "hospitality.link.membership_at_tier" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.membership" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.add_dependent_membership:apply" ] } ], "summary": "Add dependent membership", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.add_dependent_membership/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_add_dependent_membership` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.add_dependent_membership:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_add_dependent_membership", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "dependency_kind": { "enum": [ "primary", "spouse", "child", "registered_member", "transferred_legacy" ], "title": "Dependency kind (spouse / child / registered_member)", "type": "string" }, "effective_from": { "format": "date-time", "title": "Tier attachment start", "type": "string" }, "person_id": { "format": "uuid", "title": "Dependent person (typed reference)", "type": "string", "x-aerandil-references": "hospitality.person" }, "tier_id": { "format": "uuid", "title": "Tier attachment for the dependent", "type": "string", "x-aerandil-references": "hospitality.membership_tier" } }, "required": [ "dependency_kind", "tier_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership_account" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.membership_account_has_membership", "hospitality.link.membership_for_person", "hospitality.link.membership_at_tier" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.membership" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Add dependent membership (dry-run)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.add_dependent_membership/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_add_dependent_membership`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_add_dependent_membership", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "dependency_kind": { "enum": [ "primary", "spouse", "child", "registered_member", "transferred_legacy" ], "title": "Dependency kind (spouse / child / registered_member)", "type": "string" }, "effective_from": { "format": "date-time", "title": "Tier attachment start", "type": "string" }, "person_id": { "format": "uuid", "title": "Dependent person (typed reference)", "type": "string", "x-aerandil-references": "hospitality.person" }, "tier_id": { "format": "uuid", "title": "Tier attachment for the dependent", "type": "string", "x-aerandil-references": "hospitality.membership_tier" } }, "required": [ "dependency_kind", "tier_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership_account" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Add dependent membership (dry-run)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.add_dependent_membership/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_add_dependent_membership` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.add_dependent_membership:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_add_dependent_membership", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "dependency_kind": { "enum": [ "primary", "spouse", "child", "registered_member", "transferred_legacy" ], "title": "Dependency kind (spouse / child / registered_member)", "type": "string" }, "effective_from": { "format": "date-time", "title": "Tier attachment start", "type": "string" }, "person_id": { "format": "uuid", "title": "Dependent person (typed reference)", "type": "string", "x-aerandil-references": "hospitality.person" }, "tier_id": { "format": "uuid", "title": "Tier attachment for the dependent", "type": "string", "x-aerandil-references": "hospitality.membership_tier" } }, "required": [ "dependency_kind", "tier_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership_account" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Add dependent membership (rollup delta)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.add_guest_feedback_entry/apply": { "post": { "description": "Follow up on a piece of guest feedback. An `internal` entry is the house talking to itself (read on the floor); a `guest` entry is what the guest is told, and is written into the guest's open conversation at the house as a reply — on the channel they last wrote on, behind the same opt-out gate and WhatsApp window a triage's reply obeys, sent by the delivery lane when the channel is one the kernel carries. With no open conversation, or a guest who has said not to be written to, the entry is the record and says why it was not sent. `delegate_to` hands the case to a role (hubOS's delegated profile). An open case moves to `in_progress`; a closed one takes nothing more. The author is the staff member behind the principal, when it is one. Emits `guest_feedback.entry_recorded`.\n\nEffects: create hospitality.guest_feedback_entry; modify hospitality.guest_feedback; link hospitality.link.guest_feedback_entry_on_feedback; link hospitality.link.guest_feedback_entry_by_staff; link hospitality.link.guest_feedback_entry_sent_as; create hospitality.guest_message; create hospitality.guest_conversation; modify hospitality.guest_conversation; link hospitality.link.guest_conversation_for_person; link hospitality.link.guest_conversation_at_property; link hospitality.link.guest_conversation_anchored_to_reservation; link hospitality.link.guest_message_in_conversation.", "operationId": "apply_hospitality_action_add_guest_feedback_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "audience": { "enum": [ "internal", "guest" ], "title": "internal (the house to itself) or guest (what the guest is told)", "type": "string" }, "delegate_to": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "The role to hand the case to", "type": "string" }, "text": { "title": "The follow-up", "type": "string" } }, "required": [ "audience", "text" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.guest_feedback_entry_on_feedback", "hospitality.link.guest_feedback_entry_by_staff", "hospitality.link.guest_feedback_entry_sent_as", "hospitality.link.guest_conversation_for_person", "hospitality.link.guest_conversation_at_property", "hospitality.link.guest_conversation_anchored_to_reservation", "hospitality.link.guest_message_in_conversation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.guest_feedback_entry", "hospitality.guest_feedback", "hospitality.guest_message", "hospitality.guest_conversation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.add_guest_feedback_entry:apply" ] } ], "summary": "Add guest feedback entry", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.add_guest_feedback_entry/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_add_guest_feedback_entry` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.add_guest_feedback_entry:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_add_guest_feedback_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "audience": { "enum": [ "internal", "guest" ], "title": "internal (the house to itself) or guest (what the guest is told)", "type": "string" }, "delegate_to": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "The role to hand the case to", "type": "string" }, "text": { "title": "The follow-up", "type": "string" } }, "required": [ "audience", "text" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.guest_feedback_entry_on_feedback", "hospitality.link.guest_feedback_entry_by_staff", "hospitality.link.guest_feedback_entry_sent_as", "hospitality.link.guest_conversation_for_person", "hospitality.link.guest_conversation_at_property", "hospitality.link.guest_conversation_anchored_to_reservation", "hospitality.link.guest_message_in_conversation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.guest_feedback_entry", "hospitality.guest_feedback", "hospitality.guest_message", "hospitality.guest_conversation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Add guest feedback entry (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.add_guest_feedback_entry/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_add_guest_feedback_entry`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_add_guest_feedback_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "audience": { "enum": [ "internal", "guest" ], "title": "internal (the house to itself) or guest (what the guest is told)", "type": "string" }, "delegate_to": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "The role to hand the case to", "type": "string" }, "text": { "title": "The follow-up", "type": "string" } }, "required": [ "audience", "text" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Add guest feedback entry (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.add_guest_feedback_entry/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_add_guest_feedback_entry` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.add_guest_feedback_entry:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_add_guest_feedback_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "audience": { "enum": [ "internal", "guest" ], "title": "internal (the house to itself) or guest (what the guest is told)", "type": "string" }, "delegate_to": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "The role to hand the case to", "type": "string" }, "text": { "title": "The follow-up", "type": "string" } }, "required": [ "audience", "text" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Add guest feedback entry (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.add_property_to_management_agreement/apply": { "post": { "description": "Bring one property under the target HMA's coverage (the Strand-pattern portfolio agreement covers several hotels; the Condor/PHR pattern covers one). Refuses if the agreement is not active; the OneToMany link refuses a property already covered elsewhere.\n\nEffects: link hospitality.link.management_agreement_covers_property.", "operationId": "apply_hospitality_action_add_property_to_management_agreement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "property_id": { "format": "uuid", "title": "The property joining coverage", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "property_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.management_agreement" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.management_agreement_covers_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.add_property_to_management_agreement:apply" ] } ], "summary": "Add property to management agreement", "tags": [ "management" ] } }, "/v1/actions/hospitality.action.add_property_to_management_agreement/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_add_property_to_management_agreement` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.add_property_to_management_agreement:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_add_property_to_management_agreement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "property_id": { "format": "uuid", "title": "The property joining coverage", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "property_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.management_agreement" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.management_agreement_covers_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Add property to management agreement (dry-run)", "tags": [ "management" ] } }, "/v1/actions/hospitality.action.add_property_to_management_agreement/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_add_property_to_management_agreement`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_add_property_to_management_agreement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "property_id": { "format": "uuid", "title": "The property joining coverage", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "property_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.management_agreement" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Add property to management agreement (dry-run)", "tags": [ "management" ] } }, "/v1/actions/hospitality.action.add_property_to_management_agreement/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_add_property_to_management_agreement` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.add_property_to_management_agreement:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_add_property_to_management_agreement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "property_id": { "format": "uuid", "title": "The property joining coverage", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "property_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.management_agreement" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Add property to management agreement (rollup delta)", "tags": [ "management" ] } }, "/v1/actions/hospitality.action.add_verified_invocation/apply": { "post": { "description": "Append one human-blessed NL→invocation example to a `grounding_scope`'s verified-invocations repository (the Snowflake verified-query pattern). `verified_by` is stamped from the invoking principal and `verified_at` from now() — provenance is server-observed, not caller-asserted. Rejected on a retired scope. Emits `grounding_scope.invocation_verified`.\n\nEffects: modify hospitality.grounding_scope.", "operationId": "apply_hospitality_action_add_verified_invocation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "params_example": { "title": "Example params for the invocation (JSON; opaque)" }, "target_kind": { "enum": [ "action", "metric", "function" ], "title": "What the example resolves to", "type": "string" }, "target_ref": { "title": "api-name of the action / metric / function", "type": "string" }, "utterance": { "title": "The natural-language example", "type": "string" } }, "required": [ "utterance", "target_kind", "target_ref" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.grounding_scope" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.grounding_scope" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.add_verified_invocation:apply" ] } ], "summary": "Add verified invocation", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.add_verified_invocation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_add_verified_invocation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.add_verified_invocation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_add_verified_invocation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "params_example": { "title": "Example params for the invocation (JSON; opaque)" }, "target_kind": { "enum": [ "action", "metric", "function" ], "title": "What the example resolves to", "type": "string" }, "target_ref": { "title": "api-name of the action / metric / function", "type": "string" }, "utterance": { "title": "The natural-language example", "type": "string" } }, "required": [ "utterance", "target_kind", "target_ref" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.grounding_scope" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.grounding_scope" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Add verified invocation (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.add_verified_invocation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_add_verified_invocation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_add_verified_invocation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "params_example": { "title": "Example params for the invocation (JSON; opaque)" }, "target_kind": { "enum": [ "action", "metric", "function" ], "title": "What the example resolves to", "type": "string" }, "target_ref": { "title": "api-name of the action / metric / function", "type": "string" }, "utterance": { "title": "The natural-language example", "type": "string" } }, "required": [ "utterance", "target_kind", "target_ref" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.grounding_scope" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Add verified invocation (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.add_verified_invocation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_add_verified_invocation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.add_verified_invocation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_add_verified_invocation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "params_example": { "title": "Example params for the invocation (JSON; opaque)" }, "target_kind": { "enum": [ "action", "metric", "function" ], "title": "What the example resolves to", "type": "string" }, "target_ref": { "title": "api-name of the action / metric / function", "type": "string" }, "utterance": { "title": "The natural-language example", "type": "string" } }, "required": [ "utterance", "target_kind", "target_ref" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.grounding_scope" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Add verified invocation (rollup delta)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.adjust_commission/apply": { "post": { "description": "Revise what a commission row owes, keeping the previous figure on the row. Refused once the row has been paid or otherwise settled: a paid commission is corrected by a new row in the next run, never by restating history.\n\nEffects: modify hospitality.commission_detail.", "operationId": "apply_hospitality_action_adjust_commission", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "commission_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Corrected amount", "type": "object" }, "reason": { "title": "Why the figure changed", "type": "string" } }, "required": [ "commission_amount", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.commission_detail" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.commission_detail" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.adjust_commission:apply" ] } ], "summary": "Adjust commission", "tags": [ "commission" ] } }, "/v1/actions/hospitality.action.adjust_commission/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_adjust_commission` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.adjust_commission:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_adjust_commission", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "commission_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Corrected amount", "type": "object" }, "reason": { "title": "Why the figure changed", "type": "string" } }, "required": [ "commission_amount", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.commission_detail" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.commission_detail" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Adjust commission (dry-run)", "tags": [ "commission" ] } }, "/v1/actions/hospitality.action.adjust_commission/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_adjust_commission`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_adjust_commission", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "commission_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Corrected amount", "type": "object" }, "reason": { "title": "Why the figure changed", "type": "string" } }, "required": [ "commission_amount", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.commission_detail" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Adjust commission (dry-run)", "tags": [ "commission" ] } }, "/v1/actions/hospitality.action.adjust_commission/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_adjust_commission` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.adjust_commission:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_adjust_commission", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "commission_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Corrected amount", "type": "object" }, "reason": { "title": "Why the figure changed", "type": "string" } }, "required": [ "commission_amount", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.commission_detail" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Adjust commission (rollup delta)", "tags": [ "commission" ] } }, "/v1/actions/hospitality.action.adjust_stock/apply": { "post": { "description": "Correct a store's stock of a material, one of two ways. A count (`counted`): what is physically there — the level is set to it, a `count` movement carries the difference (zero when the count agrees) and the level's last_counted_at is stamped. A correction (`quantity`, signed, with the reason — breakage, expiry, theft): an `adjustment` movement by that much. Exactly one of the two. Either is refused when it would leave the level below zero, unless the store allows negative stock.\n\nEffects: create hospitality.stock_movement; create hospitality.stock_level; modify hospitality.stock_level; link hospitality.link.stock_movement_for_level; link hospitality.link.stock_level_for_material; link hospitality.link.stock_level_in_store; link hospitality.link.stock_movement_recorded_by.", "operationId": "apply_hospitality_action_adjust_stock", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "counted": { "format": "decimal", "title": "What a physical count found, in the material's unit", "type": "string" }, "material_id": { "format": "uuid", "title": "The material", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "title": "A correction by this much, signed (with the reason)", "type": "string" }, "reason": { "title": "Why (required for a correction)", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When it happened (defaults to now; a handset queueing offline sends its own time; refused when more than five minutes ahead of the kernel's clock)", "type": "string" } }, "required": [ "material_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_store" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.stock_movement_for_level", "hospitality.link.stock_level_for_material", "hospitality.link.stock_level_in_store", "hospitality.link.stock_movement_recorded_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.stock_movement", "hospitality.stock_level" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.adjust_stock:apply" ] } ], "summary": "Adjust stock", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.adjust_stock/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_adjust_stock` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.adjust_stock:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_adjust_stock", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "counted": { "format": "decimal", "title": "What a physical count found, in the material's unit", "type": "string" }, "material_id": { "format": "uuid", "title": "The material", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "title": "A correction by this much, signed (with the reason)", "type": "string" }, "reason": { "title": "Why (required for a correction)", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When it happened (defaults to now; a handset queueing offline sends its own time; refused when more than five minutes ahead of the kernel's clock)", "type": "string" } }, "required": [ "material_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_store" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.stock_movement_for_level", "hospitality.link.stock_level_for_material", "hospitality.link.stock_level_in_store", "hospitality.link.stock_movement_recorded_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.stock_movement", "hospitality.stock_level" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Adjust stock (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.adjust_stock/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_adjust_stock`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_adjust_stock", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "counted": { "format": "decimal", "title": "What a physical count found, in the material's unit", "type": "string" }, "material_id": { "format": "uuid", "title": "The material", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "title": "A correction by this much, signed (with the reason)", "type": "string" }, "reason": { "title": "Why (required for a correction)", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When it happened (defaults to now; a handset queueing offline sends its own time; refused when more than five minutes ahead of the kernel's clock)", "type": "string" } }, "required": [ "material_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_store" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Adjust stock (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.adjust_stock/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_adjust_stock` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.adjust_stock:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_adjust_stock", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "counted": { "format": "decimal", "title": "What a physical count found, in the material's unit", "type": "string" }, "material_id": { "format": "uuid", "title": "The material", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "title": "A correction by this much, signed (with the reason)", "type": "string" }, "reason": { "title": "Why (required for a correction)", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When it happened (defaults to now; a handset queueing offline sends its own time; refused when more than five minutes ahead of the kernel's clock)", "type": "string" } }, "required": [ "material_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_store" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Adjust stock (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.advance_maintenance_plan/apply": { "post": { "description": "Move a plan on once the work order it raised has closed — the completion monitor's effect. Complete: the next due date is the last plus the interval for a `fixed` plan (skipping slots a late completion overran, never raising a backlog), or the completion date plus the interval for a `floating` one; the plan returns to `scheduled`. Void: the order was withdrawn, not done — the plan returns to `scheduled` on the same due date, owed again. A no-op for an order no plan raised, an order still open, or a plan not waiting on it, so a repeated firing moves nothing twice. Emits `maintenance_plan.advanced`.\n\nEffects: modify hospitality.maintenance_plan.", "operationId": "apply_hospitality_action_advance_maintenance_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.maintenance_plan" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.advance_maintenance_plan:apply" ] } ], "summary": "Advance maintenance plan", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.advance_maintenance_plan/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_advance_maintenance_plan` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.advance_maintenance_plan:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_advance_maintenance_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.maintenance_plan" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Advance maintenance plan (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.advance_maintenance_plan/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_advance_maintenance_plan`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_advance_maintenance_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Advance maintenance plan (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.advance_maintenance_plan/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_advance_maintenance_plan` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.advance_maintenance_plan:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_advance_maintenance_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Advance maintenance plan (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.allocate_privacy_budget/apply": { "post": { "description": "Create or adjust a privacy budget account. Reducing budget below already-spent amount requires review and sets status `exhausted` rather than rewriting history (proposal §8.7). Validators (commit 5): `privacy_budget_epsilon_required_when_dp`, `privacy_budget_spent_does_not_exceed_total`, `privacy_budget_delta_required_when_mechanism_uses_delta`.\n\nEffects: create hospitality.privacy_budget_account.", "operationId": "apply_hospitality_action_allocate_privacy_budget", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "account_scope": { "enum": [ "tenant_program", "property_program", "definition", "composition_group", "output_recipient" ], "title": "Account scope", "type": "string" }, "alert_thresholds": { "items": { "format": "decimal", "type": "string" }, "title": "Optional thresholds for operator warnings", "type": "array" }, "composition_group": { "title": "Optional", "type": "string" }, "composition_strategy": { "enum": [ "basic", "advanced", "rdp", "zcdp", "operator_supplied_reviewed" ], "title": "Composition strategy", "type": "string" }, "definition_api_name": { "title": "Optional", "type": "string" }, "delta_total": { "format": "decimal", "title": "Required when delta applies", "type": "string" }, "epsilon_total": { "format": "decimal", "title": "Required for DP accounts", "type": "string" }, "mechanism_family": { "enum": [ "central_dp", "local_dp", "dp_sgd", "dp_clean_room", "none_threshold_only" ], "title": "Mechanism family", "type": "string" }, "period_end": { "format": "date-time", "title": "Required unless lifetime", "type": "string" }, "period_kind": { "enum": [ "run", "day", "month", "quarter", "year", "lifetime" ], "title": "Period kind", "type": "string" }, "period_start": { "format": "date-time", "title": "Period start", "type": "string" } }, "required": [ "account_scope", "period_kind", "period_start", "composition_strategy", "mechanism_family" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_intelligence_program" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.privacy_budget_account" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.allocate_privacy_budget:apply" ] } ], "summary": "Allocate privacy budget account", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.allocate_privacy_budget/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_allocate_privacy_budget` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.allocate_privacy_budget:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_allocate_privacy_budget", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "account_scope": { "enum": [ "tenant_program", "property_program", "definition", "composition_group", "output_recipient" ], "title": "Account scope", "type": "string" }, "alert_thresholds": { "items": { "format": "decimal", "type": "string" }, "title": "Optional thresholds for operator warnings", "type": "array" }, "composition_group": { "title": "Optional", "type": "string" }, "composition_strategy": { "enum": [ "basic", "advanced", "rdp", "zcdp", "operator_supplied_reviewed" ], "title": "Composition strategy", "type": "string" }, "definition_api_name": { "title": "Optional", "type": "string" }, "delta_total": { "format": "decimal", "title": "Required when delta applies", "type": "string" }, "epsilon_total": { "format": "decimal", "title": "Required for DP accounts", "type": "string" }, "mechanism_family": { "enum": [ "central_dp", "local_dp", "dp_sgd", "dp_clean_room", "none_threshold_only" ], "title": "Mechanism family", "type": "string" }, "period_end": { "format": "date-time", "title": "Required unless lifetime", "type": "string" }, "period_kind": { "enum": [ "run", "day", "month", "quarter", "year", "lifetime" ], "title": "Period kind", "type": "string" }, "period_start": { "format": "date-time", "title": "Period start", "type": "string" } }, "required": [ "account_scope", "period_kind", "period_start", "composition_strategy", "mechanism_family" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_intelligence_program" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.privacy_budget_account" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Allocate privacy budget account (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.allocate_privacy_budget/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_allocate_privacy_budget`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_allocate_privacy_budget", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "account_scope": { "enum": [ "tenant_program", "property_program", "definition", "composition_group", "output_recipient" ], "title": "Account scope", "type": "string" }, "alert_thresholds": { "items": { "format": "decimal", "type": "string" }, "title": "Optional thresholds for operator warnings", "type": "array" }, "composition_group": { "title": "Optional", "type": "string" }, "composition_strategy": { "enum": [ "basic", "advanced", "rdp", "zcdp", "operator_supplied_reviewed" ], "title": "Composition strategy", "type": "string" }, "definition_api_name": { "title": "Optional", "type": "string" }, "delta_total": { "format": "decimal", "title": "Required when delta applies", "type": "string" }, "epsilon_total": { "format": "decimal", "title": "Required for DP accounts", "type": "string" }, "mechanism_family": { "enum": [ "central_dp", "local_dp", "dp_sgd", "dp_clean_room", "none_threshold_only" ], "title": "Mechanism family", "type": "string" }, "period_end": { "format": "date-time", "title": "Required unless lifetime", "type": "string" }, "period_kind": { "enum": [ "run", "day", "month", "quarter", "year", "lifetime" ], "title": "Period kind", "type": "string" }, "period_start": { "format": "date-time", "title": "Period start", "type": "string" } }, "required": [ "account_scope", "period_kind", "period_start", "composition_strategy", "mechanism_family" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_intelligence_program" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Allocate privacy budget account (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.allocate_privacy_budget/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_allocate_privacy_budget` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.allocate_privacy_budget:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_allocate_privacy_budget", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "account_scope": { "enum": [ "tenant_program", "property_program", "definition", "composition_group", "output_recipient" ], "title": "Account scope", "type": "string" }, "alert_thresholds": { "items": { "format": "decimal", "type": "string" }, "title": "Optional thresholds for operator warnings", "type": "array" }, "composition_group": { "title": "Optional", "type": "string" }, "composition_strategy": { "enum": [ "basic", "advanced", "rdp", "zcdp", "operator_supplied_reviewed" ], "title": "Composition strategy", "type": "string" }, "definition_api_name": { "title": "Optional", "type": "string" }, "delta_total": { "format": "decimal", "title": "Required when delta applies", "type": "string" }, "epsilon_total": { "format": "decimal", "title": "Required for DP accounts", "type": "string" }, "mechanism_family": { "enum": [ "central_dp", "local_dp", "dp_sgd", "dp_clean_room", "none_threshold_only" ], "title": "Mechanism family", "type": "string" }, "period_end": { "format": "date-time", "title": "Required unless lifetime", "type": "string" }, "period_kind": { "enum": [ "run", "day", "month", "quarter", "year", "lifetime" ], "title": "Period kind", "type": "string" }, "period_start": { "format": "date-time", "title": "Period start", "type": "string" } }, "required": [ "account_scope", "period_kind", "period_start", "composition_strategy", "mechanism_family" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_intelligence_program" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Allocate privacy budget account (rollup delta)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.annotate_reservation/apply": { "post": { "description": "Set or clear the notes-shaped fields on a reservation: `special_requests`, `channel_reference`, `stay_context_kind` and `stay_context_notes`. Every parameter is optional and at least one must be passed; an empty (or whitespace-only) text clears its field, and the kind can be changed but not cleared. Touches nothing operational — dates, rooms, rates and status keep their own verbs — so it is legal in every reservation state, including after check-out. Notes without a stay-context kind are accepted with the validator's warning, matching the fill-the-kind-in-later workflow.\n\nEffects: modify hospitality.reservation.", "operationId": "apply_hospitality_action_annotate_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "channel_reference": { "title": "External channel reference (empty clears)", "type": "string" }, "special_requests": { "title": "Special requests (empty clears)", "type": "string" }, "stay_context_kind": { "enum": [ "leisure", "business", "anniversary", "wellness_retreat", "family", "event_attendance", "bleisure", "other" ], "title": "Stay context kind", "type": "string" }, "stay_context_notes": { "title": "Stay context notes (empty clears)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.reservation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.annotate_reservation:apply" ] } ], "summary": "Annotate reservation", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.annotate_reservation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_annotate_reservation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.annotate_reservation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_annotate_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "channel_reference": { "title": "External channel reference (empty clears)", "type": "string" }, "special_requests": { "title": "Special requests (empty clears)", "type": "string" }, "stay_context_kind": { "enum": [ "leisure", "business", "anniversary", "wellness_retreat", "family", "event_attendance", "bleisure", "other" ], "title": "Stay context kind", "type": "string" }, "stay_context_notes": { "title": "Stay context notes (empty clears)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.reservation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Annotate reservation (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.annotate_reservation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_annotate_reservation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_annotate_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "channel_reference": { "title": "External channel reference (empty clears)", "type": "string" }, "special_requests": { "title": "Special requests (empty clears)", "type": "string" }, "stay_context_kind": { "enum": [ "leisure", "business", "anniversary", "wellness_retreat", "family", "event_attendance", "bleisure", "other" ], "title": "Stay context kind", "type": "string" }, "stay_context_notes": { "title": "Stay context notes (empty clears)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Annotate reservation (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.annotate_reservation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_annotate_reservation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.annotate_reservation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_annotate_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "channel_reference": { "title": "External channel reference (empty clears)", "type": "string" }, "special_requests": { "title": "Special requests (empty clears)", "type": "string" }, "stay_context_kind": { "enum": [ "leisure", "business", "anniversary", "wellness_retreat", "family", "event_attendance", "bleisure", "other" ], "title": "Stay context kind", "type": "string" }, "stay_context_notes": { "title": "Stay context notes (empty clears)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Annotate reservation (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.append_agent_thread_message/apply": { "post": { "description": "Append one turn to an open `agent_thread` — the operator's task (`role = user`) or the agent's final reply (`role = agent`, correlated to its session trace via `session_id`). Appends into a closed thread are rejected; `parent_message_id` makes the thread branchable (the Snowflake parent-pointer pattern) and must name a message in the same thread. Refreshes the thread's `last_message_at` / `message_count` projections.\n\nEffects: create hospitality.agent_thread_message; modify hospitality.agent_thread; link hospitality.link.agent_thread_message_in_thread.", "operationId": "apply_hospitality_action_append_agent_thread_message", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "content": { "title": "The turn's text", "type": "string" }, "parent_message_id": { "title": "Branch parent message id (same thread)", "type": "string" }, "role": { "enum": [ "user", "agent" ], "title": "Who authored this turn", "type": "string" }, "session_id": { "title": "The runtime session (trace) behind an `agent` turn", "type": "string" } }, "required": [ "role", "content" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_thread" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.agent_thread_message_in_thread" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.agent_thread_message", "hospitality.agent_thread" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.append_agent_thread_message:apply" ] } ], "summary": "Append agent thread message", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.append_agent_thread_message/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_append_agent_thread_message` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.append_agent_thread_message:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_append_agent_thread_message", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "content": { "title": "The turn's text", "type": "string" }, "parent_message_id": { "title": "Branch parent message id (same thread)", "type": "string" }, "role": { "enum": [ "user", "agent" ], "title": "Who authored this turn", "type": "string" }, "session_id": { "title": "The runtime session (trace) behind an `agent` turn", "type": "string" } }, "required": [ "role", "content" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_thread" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.agent_thread_message_in_thread" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.agent_thread_message", "hospitality.agent_thread" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Append agent thread message (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.append_agent_thread_message/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_append_agent_thread_message`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_append_agent_thread_message", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "content": { "title": "The turn's text", "type": "string" }, "parent_message_id": { "title": "Branch parent message id (same thread)", "type": "string" }, "role": { "enum": [ "user", "agent" ], "title": "Who authored this turn", "type": "string" }, "session_id": { "title": "The runtime session (trace) behind an `agent` turn", "type": "string" } }, "required": [ "role", "content" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_thread" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Append agent thread message (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.append_agent_thread_message/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_append_agent_thread_message` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.append_agent_thread_message:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_append_agent_thread_message", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "content": { "title": "The turn's text", "type": "string" }, "parent_message_id": { "title": "Branch parent message id (same thread)", "type": "string" }, "role": { "enum": [ "user", "agent" ], "title": "Who authored this turn", "type": "string" }, "session_id": { "title": "The runtime session (trace) behind an `agent` turn", "type": "string" } }, "required": [ "role", "content" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_thread" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Append agent thread message (rollup delta)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.apply_channel_reservation/apply": { "post": { "description": "Land a received message in the ontology. This is the committed-upstream path, and it is the reason the seam exists: the sale completed on the partner's side before we heard about it, so our selling ceiling and our restriction wall stop being gates. Oracle states the rule for a push channel plainly — inventory and restriction checks are bypassed because the booking is already committed upstream. Refusing here would not un-sell the room; it would only leave the house ignorant of a guest who is turning up. Where the booking goes past the ceiling the breach is counted on `availability_day.committed_oversell` and reported on the delivery as `oversold_by`, so the operator sees the exposure instead of a refusal. Booking parameters are the same set `create_reservation` takes, shared in code so the two cannot drift — a divergence would be a booking an OTA can make and the desk cannot represent. Serves the `book` intent only: a cancellation goes to `cancel_channel_reservation`, which needs a reservation and nothing else, and a restatement goes to `restate_channel_reservation`, which names both the reservation and the stay. Emits `channel_reservation.applied`.\n\nEffects: create hospitality.reservation; create hospitality.reservation_room; create hospitality.reservation_night; link hospitality.link.reservation_for_property; link hospitality.link.reservation_for_guest; link hospitality.link.reservation_uses_rate_plan; link hospitality.link.reservation_uses_cancellation_policy; link hospitality.link.reservation_for_room_type; link hospitality.link.reservation_has_room; link hospitality.link.reservation_room_for_room_type; link hospitality.link.reservation_room_has_night; link hospitality.link.reservation_night_uses_rate_plan; link hospitality.link.reservation_booked_in_session; modify hospitality.availability_day; modify hospitality.channel_reservation_delivery; link hospitality.link.reservation_delivery_produced_reservation.", "operationId": "apply_hospitality_action_apply_channel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults": { "title": "Adults (single-room shape; required unless `rooms` is passed)", "type": "integer" }, "arrival_date": { "format": "date", "title": "Arrival", "type": "string" }, "booked_at": { "format": "date-time", "title": "Booking instant (defaults to now; must not be in the future or after arrival)", "type": "string" }, "channel_reference": { "title": "External channel reference (OTA confirmation / GDS locator)", "type": "string" }, "children": { "title": "Children (single-room shape; required unless `rooms` is passed)", "type": "integer" }, "confirmation_number": { "title": "Source-system confirmation number (connector loads only; defaults to a minted R-…)", "type": "string" }, "departure_date": { "format": "date", "title": "Departure", "type": "string" }, "deposit_due_at": { "format": "date-time", "title": "Explicit deposit due instant (with deposit_required_amount)", "type": "string" }, "deposit_required_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Explicit deposit amount (with deposit_due_at; overrides policy derivation)", "type": "object" }, "external_ref": { "title": "Source-system key (connector loads only; makes creation replay-safe)", "type": "string" }, "guarantee": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "title": "Protection posture (default `none`)", "type": "string" }, "guest_id": { "format": "uuid", "title": "Primary guest", "type": "string", "x-aerandil-references": "hospitality.person" }, "hold_expires_at": { "format": "date-time", "title": "When a `hold` guarantee lapses (required with hold, forbidden otherwise)", "type": "string" }, "market_segment": { "enum": [ "transient", "group", "contract" ], "title": "Demand segment (transient / group / contract)", "type": "string" }, "nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate (omit to price off the grid)", "type": "object" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type (single-room shape; required unless `rooms` is passed)", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "rooms": { "items": { "properties": { "adults": { "type": "integer" }, "children": { "type": "integer" }, "nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "room_type_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.room_type" } }, "required": [ "room_type_id", "adults", "children" ], "type": "object" }, "title": "Per-room slices for a multi-room booking (one reservation_room each)", "type": "array" }, "session_id": { "title": "Shopping session the booking was made in (its first offer's id)", "type": "string" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "Booking channel (defaults to direct_web)", "type": "string" }, "special_requests": { "title": "Special requests (cot, dietary, accessibility, room preferences)", "type": "string" }, "visitor_id": { "title": "The booking engine's key for the browser that booked, when its tag read one", "type": "string" } }, "required": [ "property_id", "guest_id", "rate_plan_id", "arrival_date", "departure_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_reservation_delivery" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.reservation_for_property", "hospitality.link.reservation_for_guest", "hospitality.link.reservation_uses_rate_plan", "hospitality.link.reservation_uses_cancellation_policy", "hospitality.link.reservation_for_room_type", "hospitality.link.reservation_has_room", "hospitality.link.reservation_room_for_room_type", "hospitality.link.reservation_room_has_night", "hospitality.link.reservation_night_uses_rate_plan", "hospitality.link.reservation_booked_in_session", "hospitality.link.reservation_delivery_produced_reservation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.reservation", "hospitality.reservation_room", "hospitality.reservation_night", "hospitality.availability_day", "hospitality.channel_reservation_delivery" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.apply_channel_reservation:apply" ] } ], "summary": "Apply channel reservation", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.apply_channel_reservation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_apply_channel_reservation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.apply_channel_reservation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_apply_channel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults": { "title": "Adults (single-room shape; required unless `rooms` is passed)", "type": "integer" }, "arrival_date": { "format": "date", "title": "Arrival", "type": "string" }, "booked_at": { "format": "date-time", "title": "Booking instant (defaults to now; must not be in the future or after arrival)", "type": "string" }, "channel_reference": { "title": "External channel reference (OTA confirmation / GDS locator)", "type": "string" }, "children": { "title": "Children (single-room shape; required unless `rooms` is passed)", "type": "integer" }, "confirmation_number": { "title": "Source-system confirmation number (connector loads only; defaults to a minted R-…)", "type": "string" }, "departure_date": { "format": "date", "title": "Departure", "type": "string" }, "deposit_due_at": { "format": "date-time", "title": "Explicit deposit due instant (with deposit_required_amount)", "type": "string" }, "deposit_required_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Explicit deposit amount (with deposit_due_at; overrides policy derivation)", "type": "object" }, "external_ref": { "title": "Source-system key (connector loads only; makes creation replay-safe)", "type": "string" }, "guarantee": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "title": "Protection posture (default `none`)", "type": "string" }, "guest_id": { "format": "uuid", "title": "Primary guest", "type": "string", "x-aerandil-references": "hospitality.person" }, "hold_expires_at": { "format": "date-time", "title": "When a `hold` guarantee lapses (required with hold, forbidden otherwise)", "type": "string" }, "market_segment": { "enum": [ "transient", "group", "contract" ], "title": "Demand segment (transient / group / contract)", "type": "string" }, "nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate (omit to price off the grid)", "type": "object" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type (single-room shape; required unless `rooms` is passed)", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "rooms": { "items": { "properties": { "adults": { "type": "integer" }, "children": { "type": "integer" }, "nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "room_type_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.room_type" } }, "required": [ "room_type_id", "adults", "children" ], "type": "object" }, "title": "Per-room slices for a multi-room booking (one reservation_room each)", "type": "array" }, "session_id": { "title": "Shopping session the booking was made in (its first offer's id)", "type": "string" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "Booking channel (defaults to direct_web)", "type": "string" }, "special_requests": { "title": "Special requests (cot, dietary, accessibility, room preferences)", "type": "string" }, "visitor_id": { "title": "The booking engine's key for the browser that booked, when its tag read one", "type": "string" } }, "required": [ "property_id", "guest_id", "rate_plan_id", "arrival_date", "departure_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_reservation_delivery" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.reservation_for_property", "hospitality.link.reservation_for_guest", "hospitality.link.reservation_uses_rate_plan", "hospitality.link.reservation_uses_cancellation_policy", "hospitality.link.reservation_for_room_type", "hospitality.link.reservation_has_room", "hospitality.link.reservation_room_for_room_type", "hospitality.link.reservation_room_has_night", "hospitality.link.reservation_night_uses_rate_plan", "hospitality.link.reservation_booked_in_session", "hospitality.link.reservation_delivery_produced_reservation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.reservation", "hospitality.reservation_room", "hospitality.reservation_night", "hospitality.availability_day", "hospitality.channel_reservation_delivery" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Apply channel reservation (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.apply_channel_reservation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_apply_channel_reservation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_apply_channel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults": { "title": "Adults (single-room shape; required unless `rooms` is passed)", "type": "integer" }, "arrival_date": { "format": "date", "title": "Arrival", "type": "string" }, "booked_at": { "format": "date-time", "title": "Booking instant (defaults to now; must not be in the future or after arrival)", "type": "string" }, "channel_reference": { "title": "External channel reference (OTA confirmation / GDS locator)", "type": "string" }, "children": { "title": "Children (single-room shape; required unless `rooms` is passed)", "type": "integer" }, "confirmation_number": { "title": "Source-system confirmation number (connector loads only; defaults to a minted R-…)", "type": "string" }, "departure_date": { "format": "date", "title": "Departure", "type": "string" }, "deposit_due_at": { "format": "date-time", "title": "Explicit deposit due instant (with deposit_required_amount)", "type": "string" }, "deposit_required_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Explicit deposit amount (with deposit_due_at; overrides policy derivation)", "type": "object" }, "external_ref": { "title": "Source-system key (connector loads only; makes creation replay-safe)", "type": "string" }, "guarantee": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "title": "Protection posture (default `none`)", "type": "string" }, "guest_id": { "format": "uuid", "title": "Primary guest", "type": "string", "x-aerandil-references": "hospitality.person" }, "hold_expires_at": { "format": "date-time", "title": "When a `hold` guarantee lapses (required with hold, forbidden otherwise)", "type": "string" }, "market_segment": { "enum": [ "transient", "group", "contract" ], "title": "Demand segment (transient / group / contract)", "type": "string" }, "nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate (omit to price off the grid)", "type": "object" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type (single-room shape; required unless `rooms` is passed)", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "rooms": { "items": { "properties": { "adults": { "type": "integer" }, "children": { "type": "integer" }, "nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "room_type_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.room_type" } }, "required": [ "room_type_id", "adults", "children" ], "type": "object" }, "title": "Per-room slices for a multi-room booking (one reservation_room each)", "type": "array" }, "session_id": { "title": "Shopping session the booking was made in (its first offer's id)", "type": "string" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "Booking channel (defaults to direct_web)", "type": "string" }, "special_requests": { "title": "Special requests (cot, dietary, accessibility, room preferences)", "type": "string" }, "visitor_id": { "title": "The booking engine's key for the browser that booked, when its tag read one", "type": "string" } }, "required": [ "property_id", "guest_id", "rate_plan_id", "arrival_date", "departure_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_reservation_delivery" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Apply channel reservation (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.apply_channel_reservation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_apply_channel_reservation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.apply_channel_reservation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_apply_channel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults": { "title": "Adults (single-room shape; required unless `rooms` is passed)", "type": "integer" }, "arrival_date": { "format": "date", "title": "Arrival", "type": "string" }, "booked_at": { "format": "date-time", "title": "Booking instant (defaults to now; must not be in the future or after arrival)", "type": "string" }, "channel_reference": { "title": "External channel reference (OTA confirmation / GDS locator)", "type": "string" }, "children": { "title": "Children (single-room shape; required unless `rooms` is passed)", "type": "integer" }, "confirmation_number": { "title": "Source-system confirmation number (connector loads only; defaults to a minted R-…)", "type": "string" }, "departure_date": { "format": "date", "title": "Departure", "type": "string" }, "deposit_due_at": { "format": "date-time", "title": "Explicit deposit due instant (with deposit_required_amount)", "type": "string" }, "deposit_required_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Explicit deposit amount (with deposit_due_at; overrides policy derivation)", "type": "object" }, "external_ref": { "title": "Source-system key (connector loads only; makes creation replay-safe)", "type": "string" }, "guarantee": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "title": "Protection posture (default `none`)", "type": "string" }, "guest_id": { "format": "uuid", "title": "Primary guest", "type": "string", "x-aerandil-references": "hospitality.person" }, "hold_expires_at": { "format": "date-time", "title": "When a `hold` guarantee lapses (required with hold, forbidden otherwise)", "type": "string" }, "market_segment": { "enum": [ "transient", "group", "contract" ], "title": "Demand segment (transient / group / contract)", "type": "string" }, "nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate (omit to price off the grid)", "type": "object" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type (single-room shape; required unless `rooms` is passed)", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "rooms": { "items": { "properties": { "adults": { "type": "integer" }, "children": { "type": "integer" }, "nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "room_type_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.room_type" } }, "required": [ "room_type_id", "adults", "children" ], "type": "object" }, "title": "Per-room slices for a multi-room booking (one reservation_room each)", "type": "array" }, "session_id": { "title": "Shopping session the booking was made in (its first offer's id)", "type": "string" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "Booking channel (defaults to direct_web)", "type": "string" }, "special_requests": { "title": "Special requests (cot, dietary, accessibility, room preferences)", "type": "string" }, "visitor_id": { "title": "The booking engine's key for the browser that booked, when its tag read one", "type": "string" } }, "required": [ "property_id", "guest_id", "rate_plan_id", "arrival_date", "departure_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_reservation_delivery" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Apply channel reservation (rollup delta)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.apply_deposit_to_folio/apply": { "post": { "description": "Carry the booking's deposit onto the stay's folio at check-in: the payments move account-to-folio, both balances follow, and `prepayment_status` becomes `applied_to_folio`. A deposit asserted on the reservation without a payment behind it — an import's shape — is credited as one instead, so the folio is right either way. Idempotent on `stay`.\n\nEffects: modify hospitality.reservation; create hospitality.payment; link hospitality.link.folio_has_payment; unlink hospitality.link.folio_has_payment; modify hospitality.folio.", "operationId": "apply_hospitality_action_apply_deposit_to_folio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_payment" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.reservation", "hospitality.payment", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.apply_deposit_to_folio:apply" ] } ], "summary": "Apply deposit to folio", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.apply_deposit_to_folio/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_apply_deposit_to_folio` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.apply_deposit_to_folio:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_apply_deposit_to_folio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_payment" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.reservation", "hospitality.payment", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Apply deposit to folio (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.apply_deposit_to_folio/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_apply_deposit_to_folio`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_apply_deposit_to_folio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Apply deposit to folio (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.apply_deposit_to_folio/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_apply_deposit_to_folio` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.apply_deposit_to_folio:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_apply_deposit_to_folio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Apply deposit to folio (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.apply_fraud_assessment/apply": { "post": { "description": "Apply a suggested fraud_risk_assessment by recording the action class actually taken: approve_proceed / decline_block / step_up_3ds_initiated / step_up_kyc_initiated / decline_with_refund / decline_with_hold / approve_with_manual_review. The diff between recommended and applied action kinds is the audit-grade edit-rate signal (proposal 0015 §9). Rejected if the assessment isn't in `suggested` state, has expired, or violates the `block_band_no_auto_approve` cross-link validator.\n\nEffects: modify hospitality.fraud_risk_assessment; link hospitality.link.fraud_assessment_chained_action_target.", "operationId": "apply_hospitality_action_apply_fraud_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "applied_action_correlation_id": { "title": "correlation_id of the chained typed action (when applicable)", "type": "string" }, "applied_action_kind": { "enum": [ "approve_proceed", "decline_block", "step_up_3ds_initiated", "step_up_kyc_initiated", "decline_with_refund", "decline_with_hold", "approve_with_manual_review" ], "title": "Action class actually taken", "type": "string" }, "modified_recommended_action": { "enum": [ "approve", "review", "step_up_3ds", "step_up_kyc", "decline", "escalate" ], "title": "Override action when operator accepts reasoning but takes a different action", "type": "string" } }, "required": [ "applied_action_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fraud_risk_assessment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.fraud_assessment_chained_action_target" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.fraud_risk_assessment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.apply_fraud_assessment:apply" ] } ], "summary": "Apply fraud assessment", "tags": [ "fraud_detection" ] } }, "/v1/actions/hospitality.action.apply_fraud_assessment/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_apply_fraud_assessment` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.apply_fraud_assessment:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_apply_fraud_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "applied_action_correlation_id": { "title": "correlation_id of the chained typed action (when applicable)", "type": "string" }, "applied_action_kind": { "enum": [ "approve_proceed", "decline_block", "step_up_3ds_initiated", "step_up_kyc_initiated", "decline_with_refund", "decline_with_hold", "approve_with_manual_review" ], "title": "Action class actually taken", "type": "string" }, "modified_recommended_action": { "enum": [ "approve", "review", "step_up_3ds", "step_up_kyc", "decline", "escalate" ], "title": "Override action when operator accepts reasoning but takes a different action", "type": "string" } }, "required": [ "applied_action_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fraud_risk_assessment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.fraud_assessment_chained_action_target" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.fraud_risk_assessment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Apply fraud assessment (dry-run)", "tags": [ "fraud_detection" ] } }, "/v1/actions/hospitality.action.apply_fraud_assessment/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_apply_fraud_assessment`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_apply_fraud_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "applied_action_correlation_id": { "title": "correlation_id of the chained typed action (when applicable)", "type": "string" }, "applied_action_kind": { "enum": [ "approve_proceed", "decline_block", "step_up_3ds_initiated", "step_up_kyc_initiated", "decline_with_refund", "decline_with_hold", "approve_with_manual_review" ], "title": "Action class actually taken", "type": "string" }, "modified_recommended_action": { "enum": [ "approve", "review", "step_up_3ds", "step_up_kyc", "decline", "escalate" ], "title": "Override action when operator accepts reasoning but takes a different action", "type": "string" } }, "required": [ "applied_action_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fraud_risk_assessment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Apply fraud assessment (dry-run)", "tags": [ "fraud_detection" ] } }, "/v1/actions/hospitality.action.apply_fraud_assessment/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_apply_fraud_assessment` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.apply_fraud_assessment:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_apply_fraud_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "applied_action_correlation_id": { "title": "correlation_id of the chained typed action (when applicable)", "type": "string" }, "applied_action_kind": { "enum": [ "approve_proceed", "decline_block", "step_up_3ds_initiated", "step_up_kyc_initiated", "decline_with_refund", "decline_with_hold", "approve_with_manual_review" ], "title": "Action class actually taken", "type": "string" }, "modified_recommended_action": { "enum": [ "approve", "review", "step_up_3ds", "step_up_kyc", "decline", "escalate" ], "title": "Override action when operator accepts reasoning but takes a different action", "type": "string" } }, "required": [ "applied_action_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fraud_risk_assessment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Apply fraud assessment (rollup delta)", "tags": [ "fraud_detection" ] } }, "/v1/actions/hospitality.action.apply_message_triage/apply": { "post": { "description": "Apply a suggested message_triage. Fan-out on recommended_action_kind: `auto_respond` chains an outbound record_guest_message; `chain_typed_action` records the chained_action_correlation_id (the host application invokes the action); `silent_acknowledge` marks applied with no outbound. Optional `modified_params` lets the operator accept the strategy but tweak the chained action's parameters (the modify-affordance per Dietvorst 2018). Rejected if the triage isn't in `suggested` state, has expired, or recommended_action_kind is escalate_to_staff / no_action.\n\nEffects: modify hospitality.message_triage; modify hospitality.guest_conversation; create hospitality.guest_message; link hospitality.link.message_triage_chained_action_target; link hospitality.link.guest_message_in_conversation.", "operationId": "apply_hospitality_action_apply_message_triage", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "chained_correlation_id": { "title": "correlation_id of the chained action (set by host application for chain_typed_action)", "type": "string" }, "modified_params": { "additionalProperties": true, "title": "Override parameters for the chained action (JSON, optional)", "type": "object" }, "modified_response_text": { "title": "Override response text for auto_respond (optional)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.message_triage" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.message_triage_chained_action_target", "hospitality.link.guest_message_in_conversation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.message_triage", "hospitality.guest_conversation", "hospitality.guest_message" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.apply_message_triage:apply" ] } ], "summary": "Apply message triage", "tags": [ "messaging" ] } }, "/v1/actions/hospitality.action.apply_message_triage/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_apply_message_triage` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.apply_message_triage:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_apply_message_triage", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "chained_correlation_id": { "title": "correlation_id of the chained action (set by host application for chain_typed_action)", "type": "string" }, "modified_params": { "additionalProperties": true, "title": "Override parameters for the chained action (JSON, optional)", "type": "object" }, "modified_response_text": { "title": "Override response text for auto_respond (optional)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.message_triage" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.message_triage_chained_action_target", "hospitality.link.guest_message_in_conversation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.message_triage", "hospitality.guest_conversation", "hospitality.guest_message" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Apply message triage (dry-run)", "tags": [ "messaging" ] } }, "/v1/actions/hospitality.action.apply_message_triage/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_apply_message_triage`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_apply_message_triage", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "chained_correlation_id": { "title": "correlation_id of the chained action (set by host application for chain_typed_action)", "type": "string" }, "modified_params": { "additionalProperties": true, "title": "Override parameters for the chained action (JSON, optional)", "type": "object" }, "modified_response_text": { "title": "Override response text for auto_respond (optional)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.message_triage" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Apply message triage (dry-run)", "tags": [ "messaging" ] } }, "/v1/actions/hospitality.action.apply_message_triage/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_apply_message_triage` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.apply_message_triage:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_apply_message_triage", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "chained_correlation_id": { "title": "correlation_id of the chained action (set by host application for chain_typed_action)", "type": "string" }, "modified_params": { "additionalProperties": true, "title": "Override parameters for the chained action (JSON, optional)", "type": "object" }, "modified_response_text": { "title": "Override response text for auto_respond (optional)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.message_triage" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Apply message triage (rollup delta)", "tags": [ "messaging" ] } }, "/v1/actions/hospitality.action.apply_pattern_remediation/apply": { "post": { "description": "Apply a suggested service_recovery_pattern by recording the remediation actually taken. For chain_typed_action the host application invokes the typed action separately and passes applied_action_correlation_id; the handler does not recursively invoke the action engine.\n\nEffects: modify hospitality.service_recovery_pattern; modify hospitality.recovery_pattern_detection_run; link hospitality.link.pattern_remediation_chained_action_target.", "operationId": "apply_hospitality_action_apply_pattern_remediation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "applied_action_correlation_id": { "title": "Host-orchestrated chained action correlation id", "type": "string" }, "applied_remediation_kind": { "enum": [ "work_order_created", "recovery_toolkit_updated", "service_register_updated", "staff_training_referred", "engineering_referred", "supply_chain_referred", "philosophy_revisited", "lineup_cadence_corrected", "manual_intervention", "no_action_applied" ], "title": "Remediation class actually applied", "type": "string" }, "modified_remediation_params": { "additionalProperties": true, "title": "Operator-modified remediation params", "type": "object" } }, "required": [ "applied_remediation_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_recovery_pattern" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.pattern_remediation_chained_action_target" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.service_recovery_pattern", "hospitality.recovery_pattern_detection_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.apply_pattern_remediation:apply" ] } ], "summary": "Apply pattern remediation", "tags": [ "recovery_pattern_detection" ] } }, "/v1/actions/hospitality.action.apply_pattern_remediation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_apply_pattern_remediation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.apply_pattern_remediation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_apply_pattern_remediation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "applied_action_correlation_id": { "title": "Host-orchestrated chained action correlation id", "type": "string" }, "applied_remediation_kind": { "enum": [ "work_order_created", "recovery_toolkit_updated", "service_register_updated", "staff_training_referred", "engineering_referred", "supply_chain_referred", "philosophy_revisited", "lineup_cadence_corrected", "manual_intervention", "no_action_applied" ], "title": "Remediation class actually applied", "type": "string" }, "modified_remediation_params": { "additionalProperties": true, "title": "Operator-modified remediation params", "type": "object" } }, "required": [ "applied_remediation_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_recovery_pattern" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.pattern_remediation_chained_action_target" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.service_recovery_pattern", "hospitality.recovery_pattern_detection_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Apply pattern remediation (dry-run)", "tags": [ "recovery_pattern_detection" ] } }, "/v1/actions/hospitality.action.apply_pattern_remediation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_apply_pattern_remediation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_apply_pattern_remediation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "applied_action_correlation_id": { "title": "Host-orchestrated chained action correlation id", "type": "string" }, "applied_remediation_kind": { "enum": [ "work_order_created", "recovery_toolkit_updated", "service_register_updated", "staff_training_referred", "engineering_referred", "supply_chain_referred", "philosophy_revisited", "lineup_cadence_corrected", "manual_intervention", "no_action_applied" ], "title": "Remediation class actually applied", "type": "string" }, "modified_remediation_params": { "additionalProperties": true, "title": "Operator-modified remediation params", "type": "object" } }, "required": [ "applied_remediation_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_recovery_pattern" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Apply pattern remediation (dry-run)", "tags": [ "recovery_pattern_detection" ] } }, "/v1/actions/hospitality.action.apply_pattern_remediation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_apply_pattern_remediation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.apply_pattern_remediation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_apply_pattern_remediation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "applied_action_correlation_id": { "title": "Host-orchestrated chained action correlation id", "type": "string" }, "applied_remediation_kind": { "enum": [ "work_order_created", "recovery_toolkit_updated", "service_register_updated", "staff_training_referred", "engineering_referred", "supply_chain_referred", "philosophy_revisited", "lineup_cadence_corrected", "manual_intervention", "no_action_applied" ], "title": "Remediation class actually applied", "type": "string" }, "modified_remediation_params": { "additionalProperties": true, "title": "Operator-modified remediation params", "type": "object" } }, "required": [ "applied_remediation_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_recovery_pattern" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Apply pattern remediation (rollup delta)", "tags": [ "recovery_pattern_detection" ] } }, "/v1/actions/hospitality.action.apply_payment/apply": { "post": { "description": "Apply a payment to a folio.\n\nEffects: create hospitality.payment; link hospitality.link.folio_has_payment; modify hospitality.folio.", "operationId": "apply_hospitality_action_apply_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "method": { "enum": [ "cash", "credit_card", "debit_card", "bank_transfer", "voucher", "loyalty_points", "direct_billing", "mobile_wallet", "ota_collected", "other" ], "title": "Method", "type": "string" }, "reference": { "title": "Reference", "type": "string" } }, "required": [ "amount", "method" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_payment" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.payment", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.apply_payment:apply" ] } ], "summary": "Apply payment", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.apply_payment/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_apply_payment` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.apply_payment:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_apply_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "method": { "enum": [ "cash", "credit_card", "debit_card", "bank_transfer", "voucher", "loyalty_points", "direct_billing", "mobile_wallet", "ota_collected", "other" ], "title": "Method", "type": "string" }, "reference": { "title": "Reference", "type": "string" } }, "required": [ "amount", "method" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_payment" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.payment", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Apply payment (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.apply_payment/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_apply_payment`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_apply_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "method": { "enum": [ "cash", "credit_card", "debit_card", "bank_transfer", "voucher", "loyalty_points", "direct_billing", "mobile_wallet", "ota_collected", "other" ], "title": "Method", "type": "string" }, "reference": { "title": "Reference", "type": "string" } }, "required": [ "amount", "method" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Apply payment (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.apply_payment/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_apply_payment` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.apply_payment:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_apply_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "method": { "enum": [ "cash", "credit_card", "debit_card", "bank_transfer", "voucher", "loyalty_points", "direct_billing", "mobile_wallet", "ota_collected", "other" ], "title": "Method", "type": "string" }, "reference": { "title": "Reference", "type": "string" } }, "required": [ "amount", "method" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Apply payment (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.apply_rate_recommendation/apply": { "post": { "description": "Apply a suggested rate_recommendation through to its target rate_per_night row. Writes to `amount` for open-pricing rate plans; on bar_grid plans it writes `bar_anchor_amount` and re-derives the row's `amount` — the price that sells — from the new anchor through the row's own modifier (percent: the ratio, absolute: the difference), rounded to the cent. Optional `modified_amount` lets the operator accept the strategy but override the number — the recommendation transitions to `modified_and_applied`, the modification is captured in `applied_amount`, and the override-rate analytics surface picks it up. Rejected if the recommendation isn't in `suggested` state or has expired.\n\nEffects: modify hospitality.rate_recommendation; modify hospitality.rate_per_night; create hospitality.derived_rate; modify hospitality.derived_rate; link hospitality.link.derived_rate_for_rate_plan; link hospitality.link.derived_rate_for_room_type; link hospitality.link.derived_rate_for_rate_per_night; link hospitality.link.recommendation_applied_to_rate_per_night; modify hospitality.rate_recommendation_run.", "operationId": "apply_hospitality_action_apply_rate_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "modified_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Override amount (defaults to recommended_amount when absent)", "type": "object" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_recommendation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.derived_rate_for_rate_plan", "hospitality.link.derived_rate_for_room_type", "hospitality.link.derived_rate_for_rate_per_night", "hospitality.link.recommendation_applied_to_rate_per_night" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.rate_recommendation", "hospitality.rate_per_night", "hospitality.derived_rate", "hospitality.rate_recommendation_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.apply_rate_recommendation:apply" ] } ], "summary": "Apply rate recommendation", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.apply_rate_recommendation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_apply_rate_recommendation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.apply_rate_recommendation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_apply_rate_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "modified_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Override amount (defaults to recommended_amount when absent)", "type": "object" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_recommendation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.derived_rate_for_rate_plan", "hospitality.link.derived_rate_for_room_type", "hospitality.link.derived_rate_for_rate_per_night", "hospitality.link.recommendation_applied_to_rate_per_night" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.rate_recommendation", "hospitality.rate_per_night", "hospitality.derived_rate", "hospitality.rate_recommendation_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Apply rate recommendation (dry-run)", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.apply_rate_recommendation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_apply_rate_recommendation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_apply_rate_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "modified_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Override amount (defaults to recommended_amount when absent)", "type": "object" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_recommendation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Apply rate recommendation (dry-run)", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.apply_rate_recommendation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_apply_rate_recommendation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.apply_rate_recommendation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_apply_rate_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "modified_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Override amount (defaults to recommended_amount when absent)", "type": "object" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_recommendation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Apply rate recommendation (rollup delta)", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.apply_restriction_recommendation/apply": { "post": { "description": "Apply a suggested restriction_recommendation: authors the `rate_restriction` row it describes through the same path `set_rate_restriction` takes — links to its scope, the `restriction.set.recorded` feed event the channel wire and the desk board read — with the recommendation's id as the row's replay key, and transitions the recommendation to `applied`. `posted_at` is the business time the restriction goes on the board (defaults to now; must not be in the future). Rejected if the recommendation isn't in `suggested` state or has expired. A `lift` recommendation authors no row: every row standing in exactly its scope over its range is stamped `lifted_at` at `posted_at` and kept, and linked to it; refused when none stands, or when one runs past the range.\n\nEffects: modify hospitality.restriction_recommendation; create hospitality.rate_restriction; link hospitality.link.room_type_has_restriction; link hospitality.link.rate_plan_has_restriction; link hospitality.link.restriction_recommendation_applied_to_rate_restriction; modify hospitality.rate_restriction; link hospitality.link.restriction_recommendation_lifted_rate_restriction; modify hospitality.rate_recommendation_run.", "operationId": "apply_hospitality_action_apply_restriction_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "posted_at": { "format": "date-time", "title": "Business time the restriction goes on the board (defaults to now; must not be in the future)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.restriction_recommendation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.room_type_has_restriction", "hospitality.link.rate_plan_has_restriction", "hospitality.link.restriction_recommendation_applied_to_rate_restriction", "hospitality.link.restriction_recommendation_lifted_rate_restriction" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.restriction_recommendation", "hospitality.rate_restriction", "hospitality.rate_recommendation_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.apply_restriction_recommendation:apply" ] } ], "summary": "Apply restriction recommendation", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.apply_restriction_recommendation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_apply_restriction_recommendation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.apply_restriction_recommendation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_apply_restriction_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "posted_at": { "format": "date-time", "title": "Business time the restriction goes on the board (defaults to now; must not be in the future)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.restriction_recommendation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.room_type_has_restriction", "hospitality.link.rate_plan_has_restriction", "hospitality.link.restriction_recommendation_applied_to_rate_restriction", "hospitality.link.restriction_recommendation_lifted_rate_restriction" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.restriction_recommendation", "hospitality.rate_restriction", "hospitality.rate_recommendation_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Apply restriction recommendation (dry-run)", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.apply_restriction_recommendation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_apply_restriction_recommendation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_apply_restriction_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "posted_at": { "format": "date-time", "title": "Business time the restriction goes on the board (defaults to now; must not be in the future)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.restriction_recommendation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Apply restriction recommendation (dry-run)", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.apply_restriction_recommendation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_apply_restriction_recommendation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.apply_restriction_recommendation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_apply_restriction_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "posted_at": { "format": "date-time", "title": "Business time the restriction goes on the board (defaults to now; must not be in the future)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.restriction_recommendation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Apply restriction recommendation (rollup delta)", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.apply_sell_limit_recommendation/apply": { "post": { "description": "Apply a suggested sell_limit_recommendation: on every availability_day row of its room type over its range, `oversell_limit` moves to the recommended headroom — or, for a `reset`, back to the row's `declared_oversell_limit` — through the overlay `set_availability` writes, the declaration kept beside it. Refused, nothing written, when a night has no ledger row, when the headroom exceeds a row's `oversell_ceiling` (the declared limit where none is set), or when a row has already sold past the limit it would set (the ledger never holds `sold` above its ceiling; a lower limit stops the selling, it cannot unsell). Links the rows moved, emits `sell_limit.applied.recorded`, and transitions the recommendation to `applied`. `posted_at` is the business time the limit takes effect (defaults to now; must not be in the future). Rejected if the recommendation isn't in `suggested` state or has expired.\n\nEffects: modify hospitality.sell_limit_recommendation; modify hospitality.availability_day; link hospitality.link.sell_limit_recommendation_applied_to_availability_day; modify hospitality.rate_recommendation_run.", "operationId": "apply_hospitality_action_apply_sell_limit_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "posted_at": { "description": "Business time the limit takes effect (defaults to now; must not be in the future)", "format": "date-time", "title": "Posted at", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.sell_limit_recommendation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.sell_limit_recommendation_applied_to_availability_day" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.sell_limit_recommendation", "hospitality.availability_day", "hospitality.rate_recommendation_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.apply_sell_limit_recommendation:apply" ] } ], "summary": "Apply sell-limit recommendation", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.apply_sell_limit_recommendation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_apply_sell_limit_recommendation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.apply_sell_limit_recommendation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_apply_sell_limit_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "posted_at": { "description": "Business time the limit takes effect (defaults to now; must not be in the future)", "format": "date-time", "title": "Posted at", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.sell_limit_recommendation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.sell_limit_recommendation_applied_to_availability_day" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.sell_limit_recommendation", "hospitality.availability_day", "hospitality.rate_recommendation_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Apply sell-limit recommendation (dry-run)", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.apply_sell_limit_recommendation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_apply_sell_limit_recommendation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_apply_sell_limit_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "posted_at": { "description": "Business time the limit takes effect (defaults to now; must not be in the future)", "format": "date-time", "title": "Posted at", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.sell_limit_recommendation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Apply sell-limit recommendation (dry-run)", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.apply_sell_limit_recommendation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_apply_sell_limit_recommendation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.apply_sell_limit_recommendation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_apply_sell_limit_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "posted_at": { "description": "Business time the limit takes effect (defaults to now; must not be in the future)", "format": "date-time", "title": "Posted at", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.sell_limit_recommendation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Apply sell-limit recommendation (rollup delta)", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.approve_agent_installation/apply": { "post": { "description": "Activate a previously-requested installation (`requested → enabled`) — the approval half of the marketplace flow opened by `request_agent_installation`. Re-checks what can have moved since the request: the registry entry's installability and the requested scopes against the entry's current declarations. Stamps `enabled_by` / `enabled_at` and emits `agent_installation.enabled`. Denial goes through `suspend_agent_installation(new_status = revoked)`.\n\nEffects: modify hospitality.agent_installation.", "operationId": "apply_hospitality_action_approve_agent_installation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_installation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.agent_installation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.approve_agent_installation:apply" ] } ], "summary": "Approve agent installation", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.approve_agent_installation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_approve_agent_installation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.approve_agent_installation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_approve_agent_installation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_installation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.agent_installation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Approve agent installation (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.approve_agent_installation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_approve_agent_installation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_approve_agent_installation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_installation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Approve agent installation (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.approve_agent_installation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_approve_agent_installation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.approve_agent_installation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_approve_agent_installation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_installation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Approve agent installation (rollup delta)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.approve_federated_analysis_definition/apply": { "post": { "description": "Record the privacy / governance approval outcome for a definition. A thin wrapper around proposal 0020 approval decisions — the domain event remains explicit. Sets the definition status to `approved`, `reviewing` (changes_requested), or `revoked` (rejected). Records the approval gate reference via the `federated_definition_reviewed_by_gate` link (proposal §8.4).\n\nEffects: modify hospitality.federated_analysis_definition; link hospitality.link.federated_definition_reviewed_by_gate.", "operationId": "apply_hospitality_action_approve_federated_analysis_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "approval_gate_id": { "title": "Approval gate id", "type": "string" }, "decision": { "enum": [ "approved", "rejected", "changes_requested" ], "title": "approved | rejected | changes_requested", "type": "string" }, "review_notes": { "title": "Required", "type": "string" } }, "required": [ "approval_gate_id", "decision", "review_notes" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_analysis_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.federated_definition_reviewed_by_gate" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.federated_analysis_definition" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.approve_federated_analysis_definition:apply" ] } ], "summary": "Approve federated analysis definition", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.approve_federated_analysis_definition/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_approve_federated_analysis_definition` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.approve_federated_analysis_definition:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_approve_federated_analysis_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "approval_gate_id": { "title": "Approval gate id", "type": "string" }, "decision": { "enum": [ "approved", "rejected", "changes_requested" ], "title": "approved | rejected | changes_requested", "type": "string" }, "review_notes": { "title": "Required", "type": "string" } }, "required": [ "approval_gate_id", "decision", "review_notes" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_analysis_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.federated_definition_reviewed_by_gate" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.federated_analysis_definition" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Approve federated analysis definition (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.approve_federated_analysis_definition/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_approve_federated_analysis_definition`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_approve_federated_analysis_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "approval_gate_id": { "title": "Approval gate id", "type": "string" }, "decision": { "enum": [ "approved", "rejected", "changes_requested" ], "title": "approved | rejected | changes_requested", "type": "string" }, "review_notes": { "title": "Required", "type": "string" } }, "required": [ "approval_gate_id", "decision", "review_notes" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_analysis_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Approve federated analysis definition (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.approve_federated_analysis_definition/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_approve_federated_analysis_definition` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.approve_federated_analysis_definition:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_approve_federated_analysis_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "approval_gate_id": { "title": "Approval gate id", "type": "string" }, "decision": { "enum": [ "approved", "rejected", "changes_requested" ], "title": "approved | rejected | changes_requested", "type": "string" }, "review_notes": { "title": "Required", "type": "string" } }, "required": [ "approval_gate_id", "decision", "review_notes" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_analysis_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Approve federated analysis definition (rollup delta)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.archive_automation/apply": { "post": { "description": "Archive an automation — terminal; the rule is retired and never fires again. The row and its run history stay (soft-delete is the ontology-wide contract). Idempotent on an already-archived automation. Emits `automation.archived`.\n\nEffects: modify hospitality.automation.", "operationId": "apply_hospitality_action_archive_automation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the automation is being archived", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.automation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.automation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.archive_automation:apply" ] } ], "summary": "Archive automation", "tags": [ "automation" ] } }, "/v1/actions/hospitality.action.archive_automation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_archive_automation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.archive_automation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_archive_automation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the automation is being archived", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.automation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.automation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Archive automation (dry-run)", "tags": [ "automation" ] } }, "/v1/actions/hospitality.action.archive_automation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_archive_automation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_archive_automation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the automation is being archived", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.automation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Archive automation (dry-run)", "tags": [ "automation" ] } }, "/v1/actions/hospitality.action.archive_automation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_archive_automation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.archive_automation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_archive_automation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the automation is being archived", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.automation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Archive automation (rollup delta)", "tags": [ "automation" ] } }, "/v1/actions/hospitality.action.assemble_dispute_evidence/apply": { "post": { "description": "Build the evidence packet for a chargeback that is awaiting evidence, from what the kernel already holds: the folio, the cancellation terms frozen at booking, the stay record, the guest, and the payment's 3DS outcome. Picks the argument from the dispute's reason and what happened to the booking (`fraud`, `no_show`, `cancellation`, `duplicate`, `service`), and records every document against the source object's id and version, plus the evidence it wanted and could not find. **Never submits.** A case can be submitted once and countering costs a fee, so that decision stays with a person; this writes a `draft`. (Move 13, 2026-10-22: a draft with no gaps still unsent 48 hours before the deadline is submitted by the night audit's sweep, as `system`.) Re-running it supersedes the unsent packet and bumps `packet_version` — the way to pick up a late folio correction. Refuses: a dispute not awaiting evidence (`needs_response` or `inquiry_needs_response`), a deadline already past, and a case whose evidence has already gone to the issuer.\n\nEffects: create hospitality.dispute_evidence_packet; modify hospitality.dispute_evidence_packet; link hospitality.link.evidence_packet_for_dispute.", "operationId": "apply_hospitality_action_assemble_dispute_evidence", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment_dispute" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.evidence_packet_for_dispute" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.dispute_evidence_packet" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.assemble_dispute_evidence:apply" ] } ], "summary": "Assemble dispute evidence", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.assemble_dispute_evidence/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_assemble_dispute_evidence` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.assemble_dispute_evidence:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_assemble_dispute_evidence", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment_dispute" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.evidence_packet_for_dispute" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.dispute_evidence_packet" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Assemble dispute evidence (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.assemble_dispute_evidence/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_assemble_dispute_evidence`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_assemble_dispute_evidence", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment_dispute" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Assemble dispute evidence (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.assemble_dispute_evidence/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_assemble_dispute_evidence` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.assemble_dispute_evidence:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_assemble_dispute_evidence", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment_dispute" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Assemble dispute evidence (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.assemble_package_sale/apply": { "post": { "description": "Attach a package to a reservation, freezing the package's current version (components + rules) into the sale's `package_version_snapshot`.\n\nEffects: create hospitality.package_sale; link hospitality.link.reservation_includes_package; link hospitality.link.package_sale_uses_package_version.", "operationId": "apply_hospitality_action_assemble_package_sale", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "contracted_price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Wrapper price the guest agreed to", "type": "object" }, "package_id": { "format": "uuid", "title": "Package", "type": "string", "x-aerandil-references": "hospitality.package" } }, "required": [ "package_id", "contracted_price" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.reservation_includes_package", "hospitality.link.package_sale_uses_package_version" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.package_sale" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.assemble_package_sale:apply" ] } ], "summary": "Assemble package sale", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.assemble_package_sale/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_assemble_package_sale` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.assemble_package_sale:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_assemble_package_sale", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "contracted_price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Wrapper price the guest agreed to", "type": "object" }, "package_id": { "format": "uuid", "title": "Package", "type": "string", "x-aerandil-references": "hospitality.package" } }, "required": [ "package_id", "contracted_price" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.reservation_includes_package", "hospitality.link.package_sale_uses_package_version" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.package_sale" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Assemble package sale (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.assemble_package_sale/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_assemble_package_sale`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_assemble_package_sale", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "contracted_price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Wrapper price the guest agreed to", "type": "object" }, "package_id": { "format": "uuid", "title": "Package", "type": "string", "x-aerandil-references": "hospitality.package" } }, "required": [ "package_id", "contracted_price" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Assemble package sale (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.assemble_package_sale/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_assemble_package_sale` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.assemble_package_sale:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_assemble_package_sale", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "contracted_price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Wrapper price the guest agreed to", "type": "object" }, "package_id": { "format": "uuid", "title": "Package", "type": "string", "x-aerandil-references": "hospitality.package" } }, "required": [ "package_id", "contracted_price" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Assemble package sale (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.assemble_training_cohort/apply": { "post": { "description": "Record the composition of a single training run as an append-only `training_cohort`. `shard_assignment` is the SISA shard → tenants map; `manifest_hash` the sha256 of the canonicalised manifest. The handler enforces the tenant `consent_policy.min_cohort_size` floor on the number of distinct tenants in the assignment (kernel-level k-anonymity). `epsilon_budget` / `delta_budget` are recorded, never enforced (proposal 0026 §6). Emits `training.cohort_assembled`.\n\nEffects: create hospitality.training_cohort.", "operationId": "apply_hospitality_action_assemble_training_cohort", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "delta_budget": { "format": "decimal", "title": "DP delta for this run (recorded, not enforced)", "type": "string" }, "epsilon_budget": { "format": "decimal", "title": "DP epsilon for this run (recorded, not enforced)", "type": "string" }, "exclusion_list_size": { "title": "Count of erased records explicitly excluded from this cohort", "type": "integer" }, "manifest_hash": { "title": "sha256 of the canonicalised cohort manifest", "type": "string" }, "model_card_uri": { "title": "Opaque pointer to the model card", "type": "string" }, "model_name": { "title": "Model this cohort trained (ApiName form)", "type": "string" }, "model_version": { "title": "Model version this run produced", "type": "integer" }, "run_id": { "title": "MLflow run id (uuid)", "type": "string" }, "shard_assignment": { "additionalProperties": true, "title": "SISA shard id → tenants assigned to that shard", "type": "object" } }, "required": [ "model_name", "model_version", "run_id", "shard_assignment", "manifest_hash" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.training_cohort" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.assemble_training_cohort:apply" ] } ], "summary": "Assemble training cohort", "tags": [ "consent" ] } }, "/v1/actions/hospitality.action.assemble_training_cohort/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_assemble_training_cohort` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.assemble_training_cohort:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_assemble_training_cohort", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "delta_budget": { "format": "decimal", "title": "DP delta for this run (recorded, not enforced)", "type": "string" }, "epsilon_budget": { "format": "decimal", "title": "DP epsilon for this run (recorded, not enforced)", "type": "string" }, "exclusion_list_size": { "title": "Count of erased records explicitly excluded from this cohort", "type": "integer" }, "manifest_hash": { "title": "sha256 of the canonicalised cohort manifest", "type": "string" }, "model_card_uri": { "title": "Opaque pointer to the model card", "type": "string" }, "model_name": { "title": "Model this cohort trained (ApiName form)", "type": "string" }, "model_version": { "title": "Model version this run produced", "type": "integer" }, "run_id": { "title": "MLflow run id (uuid)", "type": "string" }, "shard_assignment": { "additionalProperties": true, "title": "SISA shard id → tenants assigned to that shard", "type": "object" } }, "required": [ "model_name", "model_version", "run_id", "shard_assignment", "manifest_hash" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.training_cohort" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Assemble training cohort (dry-run)", "tags": [ "consent" ] } }, "/v1/actions/hospitality.action.assemble_training_cohort/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_assemble_training_cohort`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_assemble_training_cohort", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "delta_budget": { "format": "decimal", "title": "DP delta for this run (recorded, not enforced)", "type": "string" }, "epsilon_budget": { "format": "decimal", "title": "DP epsilon for this run (recorded, not enforced)", "type": "string" }, "exclusion_list_size": { "title": "Count of erased records explicitly excluded from this cohort", "type": "integer" }, "manifest_hash": { "title": "sha256 of the canonicalised cohort manifest", "type": "string" }, "model_card_uri": { "title": "Opaque pointer to the model card", "type": "string" }, "model_name": { "title": "Model this cohort trained (ApiName form)", "type": "string" }, "model_version": { "title": "Model version this run produced", "type": "integer" }, "run_id": { "title": "MLflow run id (uuid)", "type": "string" }, "shard_assignment": { "additionalProperties": true, "title": "SISA shard id → tenants assigned to that shard", "type": "object" } }, "required": [ "model_name", "model_version", "run_id", "shard_assignment", "manifest_hash" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Assemble training cohort (dry-run)", "tags": [ "consent" ] } }, "/v1/actions/hospitality.action.assemble_training_cohort/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_assemble_training_cohort` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.assemble_training_cohort:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_assemble_training_cohort", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "delta_budget": { "format": "decimal", "title": "DP delta for this run (recorded, not enforced)", "type": "string" }, "epsilon_budget": { "format": "decimal", "title": "DP epsilon for this run (recorded, not enforced)", "type": "string" }, "exclusion_list_size": { "title": "Count of erased records explicitly excluded from this cohort", "type": "integer" }, "manifest_hash": { "title": "sha256 of the canonicalised cohort manifest", "type": "string" }, "model_card_uri": { "title": "Opaque pointer to the model card", "type": "string" }, "model_name": { "title": "Model this cohort trained (ApiName form)", "type": "string" }, "model_version": { "title": "Model version this run produced", "type": "integer" }, "run_id": { "title": "MLflow run id (uuid)", "type": "string" }, "shard_assignment": { "additionalProperties": true, "title": "SISA shard id → tenants assigned to that shard", "type": "object" } }, "required": [ "model_name", "model_version", "run_id", "shard_assignment", "manifest_hash" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Assemble training cohort (rollup delta)", "tags": [ "consent" ] } }, "/v1/actions/hospitality.action.assign_approval_gate/apply": { "post": { "description": "Narrow a live gate to specific assignees — the approver-side assignment-tracking half of the §4.4.1 lifecycle. Replaces `assigned_to` with the supplied principal set (which must not intersect `excluded_principal_ids`), advances a `requested` gate to `assigned` (later statuses never regress), and emits `approval_gate.assigned` whenever the assignee set changes. Idempotent when the set is unchanged.\n\nEffects: modify hospitality.approval_gate.", "operationId": "apply_hospitality_action_assign_approval_gate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "assigned_to": { "items": { "type": "string" }, "title": "Principal stable ids to assign (replaces the current set)", "type": "array" } }, "required": [ "assigned_to" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.approval_gate" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.approval_gate" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.assign_approval_gate:apply" ] } ], "summary": "Assign approval gate", "tags": [ "approvals" ] } }, "/v1/actions/hospitality.action.assign_approval_gate/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_assign_approval_gate` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.assign_approval_gate:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_assign_approval_gate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "assigned_to": { "items": { "type": "string" }, "title": "Principal stable ids to assign (replaces the current set)", "type": "array" } }, "required": [ "assigned_to" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.approval_gate" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.approval_gate" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Assign approval gate (dry-run)", "tags": [ "approvals" ] } }, "/v1/actions/hospitality.action.assign_approval_gate/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_assign_approval_gate`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_assign_approval_gate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "assigned_to": { "items": { "type": "string" }, "title": "Principal stable ids to assign (replaces the current set)", "type": "array" } }, "required": [ "assigned_to" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.approval_gate" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Assign approval gate (dry-run)", "tags": [ "approvals" ] } }, "/v1/actions/hospitality.action.assign_approval_gate/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_assign_approval_gate` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.assign_approval_gate:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_assign_approval_gate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "assigned_to": { "items": { "type": "string" }, "title": "Principal stable ids to assign (replaces the current set)", "type": "array" } }, "required": [ "assigned_to" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.approval_gate" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Assign approval gate (rollup delta)", "tags": [ "approvals" ] } }, "/v1/actions/hospitality.action.assign_brand_to_venue/apply": { "post": { "description": "Link a venue_brand to the target venue via the M:N `venue_has_brand` link with effective dates. A venue can carry multiple concurrent brands (a multi-concept day-cafe / night-bar venue carries two active links); a single venue brand attaches to many venues across many properties (Cecconi's at 15+ Soho House locations). The temporal link tracks the participation window so brand transitions can be expressed without losing history.\n\nEffects: link hospitality.link.venue_has_brand.", "operationId": "apply_hospitality_action_assign_brand_to_venue", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date-time", "title": "Brand attachment start", "type": "string" }, "effective_to": { "format": "date-time", "title": "Brand attachment end (null when ongoing)", "type": "string" }, "venue_brand_id": { "format": "uuid", "title": "Venue brand", "type": "string", "x-aerandil-references": "hospitality.venue_brand" } }, "required": [ "venue_brand_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.venue_has_brand" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.assign_brand_to_venue:apply" ] } ], "summary": "Assign brand to venue", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.assign_brand_to_venue/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_assign_brand_to_venue` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.assign_brand_to_venue:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_assign_brand_to_venue", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date-time", "title": "Brand attachment start", "type": "string" }, "effective_to": { "format": "date-time", "title": "Brand attachment end (null when ongoing)", "type": "string" }, "venue_brand_id": { "format": "uuid", "title": "Venue brand", "type": "string", "x-aerandil-references": "hospitality.venue_brand" } }, "required": [ "venue_brand_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.venue_has_brand" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Assign brand to venue (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.assign_brand_to_venue/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_assign_brand_to_venue`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_assign_brand_to_venue", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date-time", "title": "Brand attachment start", "type": "string" }, "effective_to": { "format": "date-time", "title": "Brand attachment end (null when ongoing)", "type": "string" }, "venue_brand_id": { "format": "uuid", "title": "Venue brand", "type": "string", "x-aerandil-references": "hospitality.venue_brand" } }, "required": [ "venue_brand_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Assign brand to venue (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.assign_brand_to_venue/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_assign_brand_to_venue` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.assign_brand_to_venue:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_assign_brand_to_venue", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date-time", "title": "Brand attachment start", "type": "string" }, "effective_to": { "format": "date-time", "title": "Brand attachment end (null when ongoing)", "type": "string" }, "venue_brand_id": { "format": "uuid", "title": "Venue brand", "type": "string", "x-aerandil-references": "hospitality.venue_brand" } }, "required": [ "venue_brand_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Assign brand to venue (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.assign_housekeeping_task/apply": { "post": { "description": "Assign (or reassign) the task to an attendant — the edge re-points, so a task has at most one current assignee and the per-attendant task sheet is simply the projection over (assignee, business_date). Refuses a task already complete or skipped. Name `group_id` instead of `staff_member_id` (exactly one, 2026-10-14) to give the task to a worker group — an active housekeeping, public_areas or other group at the task's house, whose `floors` (when it names any) include the floor of the task's room or area; the member who starts it takes it. A task is assigned to a person or a group, never both: each assignment replaces the other edge. Emits `housekeeping.task.assigned`, or `housekeeping.task.assigned_to_group` with the group's members. The task's `assignee_id` / `group_id` follow the edge in the same write (2026-10-15).\n\nEffects: link hospitality.link.housekeeping_task_assigned_to; unlink hospitality.link.housekeeping_task_assigned_to; link hospitality.link.housekeeping_task_assigned_to_group; unlink hospitality.link.housekeeping_task_assigned_to_group; modify hospitality.housekeeping_task.", "operationId": "apply_hospitality_action_assign_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "group_id": { "format": "uuid", "title": "Worker group to assign instead of an attendant", "type": "string", "x-aerandil-references": "hospitality.worker_group" }, "staff_member_id": { "format": "uuid", "title": "Attendant to assign (or group_id)", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.housekeeping_task_assigned_to", "hospitality.link.housekeeping_task_assigned_to_group" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.assign_housekeeping_task:apply" ] } ], "summary": "Assign housekeeping task", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.assign_housekeeping_task/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_assign_housekeeping_task` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.assign_housekeeping_task:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_assign_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "group_id": { "format": "uuid", "title": "Worker group to assign instead of an attendant", "type": "string", "x-aerandil-references": "hospitality.worker_group" }, "staff_member_id": { "format": "uuid", "title": "Attendant to assign (or group_id)", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.housekeeping_task_assigned_to", "hospitality.link.housekeeping_task_assigned_to_group" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Assign housekeeping task (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.assign_housekeeping_task/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_assign_housekeeping_task`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_assign_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "group_id": { "format": "uuid", "title": "Worker group to assign instead of an attendant", "type": "string", "x-aerandil-references": "hospitality.worker_group" }, "staff_member_id": { "format": "uuid", "title": "Attendant to assign (or group_id)", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Assign housekeeping task (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.assign_housekeeping_task/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_assign_housekeeping_task` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.assign_housekeeping_task:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_assign_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "group_id": { "format": "uuid", "title": "Worker group to assign instead of an attendant", "type": "string", "x-aerandil-references": "hospitality.worker_group" }, "staff_member_id": { "format": "uuid", "title": "Attendant to assign (or group_id)", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Assign housekeeping task (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.assign_operator_to_venue/apply": { "post": { "description": "Attach a white-label operator company to the target venue via the temporal `venue_has_operator` link. Distinct from `assign_brand_to_venue` (the brand customers see) and from property ownership — three independent concerns. The operator concern surfaces in Hakkasan-at-Wynn and Catch-at-W patterns; the operator company is a `company` row, not a new object type.\n\nEffects: link hospitality.link.venue_has_operator; unlink hospitality.link.venue_has_operator.", "operationId": "apply_hospitality_action_assign_operator_to_venue", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date-time", "title": "Operator attachment start", "type": "string" }, "effective_to": { "format": "date-time", "title": "Operator attachment end (null when ongoing)", "type": "string" }, "operator_company_id": { "format": "uuid", "title": "Operator company", "type": "string", "x-aerandil-references": "hospitality.company" } }, "required": [ "operator_company_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.venue_has_operator" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.assign_operator_to_venue:apply" ] } ], "summary": "Assign operator to venue", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.assign_operator_to_venue/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_assign_operator_to_venue` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.assign_operator_to_venue:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_assign_operator_to_venue", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date-time", "title": "Operator attachment start", "type": "string" }, "effective_to": { "format": "date-time", "title": "Operator attachment end (null when ongoing)", "type": "string" }, "operator_company_id": { "format": "uuid", "title": "Operator company", "type": "string", "x-aerandil-references": "hospitality.company" } }, "required": [ "operator_company_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.venue_has_operator" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Assign operator to venue (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.assign_operator_to_venue/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_assign_operator_to_venue`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_assign_operator_to_venue", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date-time", "title": "Operator attachment start", "type": "string" }, "effective_to": { "format": "date-time", "title": "Operator attachment end (null when ongoing)", "type": "string" }, "operator_company_id": { "format": "uuid", "title": "Operator company", "type": "string", "x-aerandil-references": "hospitality.company" } }, "required": [ "operator_company_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Assign operator to venue (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.assign_operator_to_venue/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_assign_operator_to_venue` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.assign_operator_to_venue:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_assign_operator_to_venue", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date-time", "title": "Operator attachment start", "type": "string" }, "effective_to": { "format": "date-time", "title": "Operator attachment end (null when ongoing)", "type": "string" }, "operator_company_id": { "format": "uuid", "title": "Operator company", "type": "string", "x-aerandil-references": "hospitality.company" } }, "required": [ "operator_company_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Assign operator to venue (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.assign_room/apply": { "post": { "description": "Assign a specific physical room to a single-room reservation. The handler rejects the action if the room's room_type does not match the reservation's reserved room_type, and rejects multi-room reservations outright — one physical room cannot serve N reservation_rooms; use `assign_room_for_reservation_room` per room instead. Re-assigning the room already assigned is an idempotent no-op.\n\nEffects: modify hospitality.reservation_room; link hospitality.link.reservation_room_assigned_to.", "operationId": "apply_hospitality_action_assign_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "room_id": { "format": "uuid", "title": "Room", "type": "string", "x-aerandil-references": "hospitality.room" } }, "required": [ "room_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.reservation_room_assigned_to" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.reservation_room" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.assign_room:apply" ] } ], "summary": "Assign room", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.assign_room/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_assign_room` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.assign_room:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_assign_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "room_id": { "format": "uuid", "title": "Room", "type": "string", "x-aerandil-references": "hospitality.room" } }, "required": [ "room_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.reservation_room_assigned_to" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.reservation_room" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Assign room (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.assign_room/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_assign_room`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_assign_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "room_id": { "format": "uuid", "title": "Room", "type": "string", "x-aerandil-references": "hospitality.room" } }, "required": [ "room_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Assign room (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.assign_room/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_assign_room` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.assign_room:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_assign_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "room_id": { "format": "uuid", "title": "Room", "type": "string", "x-aerandil-references": "hospitality.room" } }, "required": [ "room_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Assign room (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.assign_room_for_reservation_room/apply": { "post": { "description": "Assign a specific physical room to one `reservation_room` — the multi-room-booking variant of `assign_room`. The room's room_type must match the reservation_room's own reserved room_type, and the parent reservation must be pre-check-in. Re-assigning to a different room is a room move (the prior assignment link is replaced); re-assigning the same room is a no-op.\n\nEffects: modify hospitality.reservation_room; link hospitality.link.reservation_room_assigned_to; unlink hospitality.link.reservation_room_assigned_to.", "operationId": "apply_hospitality_action_assign_room_for_reservation_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "room_id": { "format": "uuid", "title": "Room", "type": "string", "x-aerandil-references": "hospitality.room" } }, "required": [ "room_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation_room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.reservation_room_assigned_to" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.reservation_room" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.assign_room_for_reservation_room:apply" ] } ], "summary": "Assign room for reservation room", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.assign_room_for_reservation_room/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_assign_room_for_reservation_room` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.assign_room_for_reservation_room:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_assign_room_for_reservation_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "room_id": { "format": "uuid", "title": "Room", "type": "string", "x-aerandil-references": "hospitality.room" } }, "required": [ "room_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation_room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.reservation_room_assigned_to" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.reservation_room" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Assign room for reservation room (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.assign_room_for_reservation_room/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_assign_room_for_reservation_room`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_assign_room_for_reservation_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "room_id": { "format": "uuid", "title": "Room", "type": "string", "x-aerandil-references": "hospitality.room" } }, "required": [ "room_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation_room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Assign room for reservation room (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.assign_room_for_reservation_room/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_assign_room_for_reservation_room` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.assign_room_for_reservation_room:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_assign_room_for_reservation_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "room_id": { "format": "uuid", "title": "Room", "type": "string", "x-aerandil-references": "hospitality.room" } }, "required": [ "room_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation_room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Assign room for reservation room (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.assign_work_order/apply": { "post": { "description": "Assign (or reassign) the work order to an engineer — the edge re-points, so an order has at most one current assignee and the engineering board is a projection. Refuses an order already complete or void. Name `group_id` instead of `staff_member_id` (exactly one, 2026-10-14) to give the order to a worker group — an active maintenance or other group at the order's house, whose `floors` (when it names any) include the floor of the order's room; the member who starts it takes it. An order is assigned to a person or a group, never both: each assignment replaces the other edge. Emits `work_order.assigned`, or `work_order.assigned_to_group` with the group's members.\n\nEffects: link hospitality.link.work_order_assigned_to; unlink hospitality.link.work_order_assigned_to; link hospitality.link.work_order_assigned_to_group; unlink hospitality.link.work_order_assigned_to_group; modify hospitality.work_order.", "operationId": "apply_hospitality_action_assign_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "group_id": { "format": "uuid", "title": "Worker group to assign instead of an engineer", "type": "string", "x-aerandil-references": "hospitality.worker_group" }, "staff_member_id": { "format": "uuid", "title": "Engineer to assign (or group_id)", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.work_order_assigned_to", "hospitality.link.work_order_assigned_to_group" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.work_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.assign_work_order:apply" ] } ], "summary": "Assign work order", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.assign_work_order/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_assign_work_order` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.assign_work_order:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_assign_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "group_id": { "format": "uuid", "title": "Worker group to assign instead of an engineer", "type": "string", "x-aerandil-references": "hospitality.worker_group" }, "staff_member_id": { "format": "uuid", "title": "Engineer to assign (or group_id)", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.work_order_assigned_to", "hospitality.link.work_order_assigned_to_group" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.work_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Assign work order (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.assign_work_order/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_assign_work_order`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_assign_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "group_id": { "format": "uuid", "title": "Worker group to assign instead of an engineer", "type": "string", "x-aerandil-references": "hospitality.worker_group" }, "staff_member_id": { "format": "uuid", "title": "Engineer to assign (or group_id)", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Assign work order (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.assign_work_order/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_assign_work_order` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.assign_work_order:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_assign_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "group_id": { "format": "uuid", "title": "Worker group to assign instead of an engineer", "type": "string", "x-aerandil-references": "hospitality.worker_group" }, "staff_member_id": { "format": "uuid", "title": "Engineer to assign (or group_id)", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Assign work order (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.authorise_charge_with_review/apply": { "post": { "description": "Record a payment authorisation event with the fraud-risk assessment gate enforced as a structural precondition. Validators reject: assessment not fresh / suggested, band = block, assessment already linked to another payment, payment token shaped like a PAN, liability-shift basis incoherent with authentication outcome, TRA / low-value amount ceiling exceeded, capture_strategy incoherent with band, folio closed or void. Atomically inserts a Payment row (status = pending for manual_capture_after_review / authorise_only, settled for auto_capture_if_clear) with the decision-provenance trio, and transitions the assessment to applied with applied_action_kind = approve_proceed.\n\nEffects: create hospitality.payment; modify hospitality.fraud_risk_assessment; modify hospitality.folio; link hospitality.link.folio_has_payment; link hospitality.link.payment_for_fraud_assessment.", "operationId": "apply_hospitality_action_authorise_charge_with_review", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "auth_correlation_id": { "title": "Host's PSP authorisation reference", "type": "string" }, "authentication_outcome": { "enum": [ "frictionless", "challenge_passed", "challenge_failed", "attempted", "pending_decoupled", "not_applicable" ], "title": "EMV 3DS 2.2 authentication outcome (required when liability_shift_basis = three_ds2_authenticated)", "type": "string" }, "authorisation_expires_at": { "format": "date-time", "title": "Scheme's authorisation-validity window", "type": "string" }, "capture_strategy": { "enum": [ "auto_capture_if_clear", "manual_capture_after_review", "authorise_only" ], "title": "Capture strategy", "type": "string" }, "decision_provider": { "title": "Fraud-decision vendor (denormalised from assessment.vendor_id)", "type": "string" }, "decision_provider_case_id": { "title": "Vendor's case / decision identifier", "type": "string" }, "fraud_risk_assessment_ref": { "format": "uuid", "title": "Gating assessment", "type": "string", "x-aerandil-references": "hospitality.fraud_risk_assessment" }, "hold_purpose": { "enum": [ "booking", "check_in", "top_up", "re_placement", "incidentals", "no_show", "post_stay", "other" ], "title": "Why the hold is placed (booking, check_in, top_up, re_placement, incidentals, no_show, post_stay, other)", "type": "string" }, "liability_shift_basis": { "enum": [ "three_ds2_authenticated", "provider_guarantee", "none" ], "title": "Liability-shift basis (per-decision, not per-vendor)", "type": "string" }, "method": { "enum": [ "cash", "credit_card", "debit_card", "bank_transfer", "voucher", "loyalty_points", "direct_billing", "mobile_wallet", "ota_collected", "other" ], "title": "Payment method", "type": "string" }, "payment_method_token": { "title": "PSP-issued opaque token (must NOT be a PAN)", "type": "string" }, "reference": { "title": "Reference", "type": "string" }, "sca_exemption_claimed": { "enum": [ "none", "low_value", "tra", "mit", "trusted_beneficiary", "secure_corporate" ], "title": "PSD2 SCA exemption claimed (defaults to none)", "type": "string" } }, "required": [ "fraud_risk_assessment_ref", "amount", "method", "capture_strategy", "decision_provider", "decision_provider_case_id", "liability_shift_basis" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_payment", "hospitality.link.payment_for_fraud_assessment" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.payment", "hospitality.fraud_risk_assessment", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.authorise_charge_with_review:apply" ] } ], "summary": "Authorise charge with review", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.authorise_charge_with_review/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_authorise_charge_with_review` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.authorise_charge_with_review:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_authorise_charge_with_review", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "auth_correlation_id": { "title": "Host's PSP authorisation reference", "type": "string" }, "authentication_outcome": { "enum": [ "frictionless", "challenge_passed", "challenge_failed", "attempted", "pending_decoupled", "not_applicable" ], "title": "EMV 3DS 2.2 authentication outcome (required when liability_shift_basis = three_ds2_authenticated)", "type": "string" }, "authorisation_expires_at": { "format": "date-time", "title": "Scheme's authorisation-validity window", "type": "string" }, "capture_strategy": { "enum": [ "auto_capture_if_clear", "manual_capture_after_review", "authorise_only" ], "title": "Capture strategy", "type": "string" }, "decision_provider": { "title": "Fraud-decision vendor (denormalised from assessment.vendor_id)", "type": "string" }, "decision_provider_case_id": { "title": "Vendor's case / decision identifier", "type": "string" }, "fraud_risk_assessment_ref": { "format": "uuid", "title": "Gating assessment", "type": "string", "x-aerandil-references": "hospitality.fraud_risk_assessment" }, "hold_purpose": { "enum": [ "booking", "check_in", "top_up", "re_placement", "incidentals", "no_show", "post_stay", "other" ], "title": "Why the hold is placed (booking, check_in, top_up, re_placement, incidentals, no_show, post_stay, other)", "type": "string" }, "liability_shift_basis": { "enum": [ "three_ds2_authenticated", "provider_guarantee", "none" ], "title": "Liability-shift basis (per-decision, not per-vendor)", "type": "string" }, "method": { "enum": [ "cash", "credit_card", "debit_card", "bank_transfer", "voucher", "loyalty_points", "direct_billing", "mobile_wallet", "ota_collected", "other" ], "title": "Payment method", "type": "string" }, "payment_method_token": { "title": "PSP-issued opaque token (must NOT be a PAN)", "type": "string" }, "reference": { "title": "Reference", "type": "string" }, "sca_exemption_claimed": { "enum": [ "none", "low_value", "tra", "mit", "trusted_beneficiary", "secure_corporate" ], "title": "PSD2 SCA exemption claimed (defaults to none)", "type": "string" } }, "required": [ "fraud_risk_assessment_ref", "amount", "method", "capture_strategy", "decision_provider", "decision_provider_case_id", "liability_shift_basis" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_payment", "hospitality.link.payment_for_fraud_assessment" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.payment", "hospitality.fraud_risk_assessment", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Authorise charge with review (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.authorise_charge_with_review/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_authorise_charge_with_review`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_authorise_charge_with_review", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "auth_correlation_id": { "title": "Host's PSP authorisation reference", "type": "string" }, "authentication_outcome": { "enum": [ "frictionless", "challenge_passed", "challenge_failed", "attempted", "pending_decoupled", "not_applicable" ], "title": "EMV 3DS 2.2 authentication outcome (required when liability_shift_basis = three_ds2_authenticated)", "type": "string" }, "authorisation_expires_at": { "format": "date-time", "title": "Scheme's authorisation-validity window", "type": "string" }, "capture_strategy": { "enum": [ "auto_capture_if_clear", "manual_capture_after_review", "authorise_only" ], "title": "Capture strategy", "type": "string" }, "decision_provider": { "title": "Fraud-decision vendor (denormalised from assessment.vendor_id)", "type": "string" }, "decision_provider_case_id": { "title": "Vendor's case / decision identifier", "type": "string" }, "fraud_risk_assessment_ref": { "format": "uuid", "title": "Gating assessment", "type": "string", "x-aerandil-references": "hospitality.fraud_risk_assessment" }, "hold_purpose": { "enum": [ "booking", "check_in", "top_up", "re_placement", "incidentals", "no_show", "post_stay", "other" ], "title": "Why the hold is placed (booking, check_in, top_up, re_placement, incidentals, no_show, post_stay, other)", "type": "string" }, "liability_shift_basis": { "enum": [ "three_ds2_authenticated", "provider_guarantee", "none" ], "title": "Liability-shift basis (per-decision, not per-vendor)", "type": "string" }, "method": { "enum": [ "cash", "credit_card", "debit_card", "bank_transfer", "voucher", "loyalty_points", "direct_billing", "mobile_wallet", "ota_collected", "other" ], "title": "Payment method", "type": "string" }, "payment_method_token": { "title": "PSP-issued opaque token (must NOT be a PAN)", "type": "string" }, "reference": { "title": "Reference", "type": "string" }, "sca_exemption_claimed": { "enum": [ "none", "low_value", "tra", "mit", "trusted_beneficiary", "secure_corporate" ], "title": "PSD2 SCA exemption claimed (defaults to none)", "type": "string" } }, "required": [ "fraud_risk_assessment_ref", "amount", "method", "capture_strategy", "decision_provider", "decision_provider_case_id", "liability_shift_basis" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Authorise charge with review (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.authorise_charge_with_review/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_authorise_charge_with_review` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.authorise_charge_with_review:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_authorise_charge_with_review", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "auth_correlation_id": { "title": "Host's PSP authorisation reference", "type": "string" }, "authentication_outcome": { "enum": [ "frictionless", "challenge_passed", "challenge_failed", "attempted", "pending_decoupled", "not_applicable" ], "title": "EMV 3DS 2.2 authentication outcome (required when liability_shift_basis = three_ds2_authenticated)", "type": "string" }, "authorisation_expires_at": { "format": "date-time", "title": "Scheme's authorisation-validity window", "type": "string" }, "capture_strategy": { "enum": [ "auto_capture_if_clear", "manual_capture_after_review", "authorise_only" ], "title": "Capture strategy", "type": "string" }, "decision_provider": { "title": "Fraud-decision vendor (denormalised from assessment.vendor_id)", "type": "string" }, "decision_provider_case_id": { "title": "Vendor's case / decision identifier", "type": "string" }, "fraud_risk_assessment_ref": { "format": "uuid", "title": "Gating assessment", "type": "string", "x-aerandil-references": "hospitality.fraud_risk_assessment" }, "hold_purpose": { "enum": [ "booking", "check_in", "top_up", "re_placement", "incidentals", "no_show", "post_stay", "other" ], "title": "Why the hold is placed (booking, check_in, top_up, re_placement, incidentals, no_show, post_stay, other)", "type": "string" }, "liability_shift_basis": { "enum": [ "three_ds2_authenticated", "provider_guarantee", "none" ], "title": "Liability-shift basis (per-decision, not per-vendor)", "type": "string" }, "method": { "enum": [ "cash", "credit_card", "debit_card", "bank_transfer", "voucher", "loyalty_points", "direct_billing", "mobile_wallet", "ota_collected", "other" ], "title": "Payment method", "type": "string" }, "payment_method_token": { "title": "PSP-issued opaque token (must NOT be a PAN)", "type": "string" }, "reference": { "title": "Reference", "type": "string" }, "sca_exemption_claimed": { "enum": [ "none", "low_value", "tra", "mit", "trusted_beneficiary", "secure_corporate" ], "title": "PSD2 SCA exemption claimed (defaults to none)", "type": "string" } }, "required": [ "fraud_risk_assessment_ref", "amount", "method", "capture_strategy", "decision_provider", "decision_provider_case_id", "liability_shift_basis" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Authorise charge with review (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.begin_appointment_service/apply": { "post": { "description": "The treatment began: checked_in → in_service (Book4Time's In-Service block; Zenoti's progress = Start). The actual start instant feeds treatment-room utilisation reads against the booked window. Business time: `service_started_at` defaults to now. Emits `spa.appointment_in_service`.\n\nEffects: modify hospitality.appointment.", "operationId": "apply_hospitality_action_begin_appointment_service", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "service_started_at": { "format": "date-time", "title": "When the treatment actually began (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.appointment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.begin_appointment_service:apply" ] } ], "summary": "Begin appointment service", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.begin_appointment_service/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_begin_appointment_service` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.begin_appointment_service:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_begin_appointment_service", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "service_started_at": { "format": "date-time", "title": "When the treatment actually began (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.appointment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Begin appointment service (dry-run)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.begin_appointment_service/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_begin_appointment_service`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_begin_appointment_service", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "service_started_at": { "format": "date-time", "title": "When the treatment actually began (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Begin appointment service (dry-run)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.begin_appointment_service/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_begin_appointment_service` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.begin_appointment_service:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_begin_appointment_service", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "service_started_at": { "format": "date-time", "title": "When the treatment actually began (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Begin appointment service (rollup delta)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.bind_commission_agreement/apply": { "post": { "description": "Open a commission agreement between a property and a travel agent, closing whichever agreement was open before. Terms are never edited in place — a renegotiation is a new period, so a commission accrued under the old rate still answers `which rate applied` correctly.\n\nEffects: create hospitality.commission_agreement; modify hospitality.commission_agreement; link hospitality.link.commission_agreement_for_company; link hospitality.link.commission_agreement_for_property.", "operationId": "apply_hospitality_action_bind_commission_agreement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "commission_flat_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Per-booking flat commission", "type": "object" }, "commission_kind": { "enum": [ "percent_of_revenue", "per_booking_flat", "per_booking_plus_percent", "none" ], "title": "Commission kind", "type": "string" }, "commission_rate": { "format": "decimal", "title": "Decimal share of commissionable revenue", "type": "string" }, "company_id": { "format": "uuid", "title": "The agent, tour operator, wholesaler or consortium", "type": "string", "x-aerandil-references": "hospitality.company" }, "effective_from": { "format": "date", "title": "First date the terms apply", "type": "string" }, "minimum_payment_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Do not pay this agent below this amount", "type": "object" }, "notes": { "title": "Contract notes", "type": "string" }, "property_id": { "format": "uuid", "title": "Property the terms apply at", "type": "string", "x-aerandil-references": "hospitality.property" }, "tax_treatment": { "enum": [ "standard", "reverse_charge", "exempt" ], "title": "VAT posture of this agent's commission", "type": "string" } }, "required": [ "company_id", "property_id", "effective_from", "commission_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.commission_agreement_for_company", "hospitality.link.commission_agreement_for_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.commission_agreement" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.bind_commission_agreement:apply" ] } ], "summary": "Bind commission agreement", "tags": [ "commission" ] } }, "/v1/actions/hospitality.action.bind_commission_agreement/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_bind_commission_agreement` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.bind_commission_agreement:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_bind_commission_agreement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "commission_flat_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Per-booking flat commission", "type": "object" }, "commission_kind": { "enum": [ "percent_of_revenue", "per_booking_flat", "per_booking_plus_percent", "none" ], "title": "Commission kind", "type": "string" }, "commission_rate": { "format": "decimal", "title": "Decimal share of commissionable revenue", "type": "string" }, "company_id": { "format": "uuid", "title": "The agent, tour operator, wholesaler or consortium", "type": "string", "x-aerandil-references": "hospitality.company" }, "effective_from": { "format": "date", "title": "First date the terms apply", "type": "string" }, "minimum_payment_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Do not pay this agent below this amount", "type": "object" }, "notes": { "title": "Contract notes", "type": "string" }, "property_id": { "format": "uuid", "title": "Property the terms apply at", "type": "string", "x-aerandil-references": "hospitality.property" }, "tax_treatment": { "enum": [ "standard", "reverse_charge", "exempt" ], "title": "VAT posture of this agent's commission", "type": "string" } }, "required": [ "company_id", "property_id", "effective_from", "commission_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.commission_agreement_for_company", "hospitality.link.commission_agreement_for_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.commission_agreement" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Bind commission agreement (dry-run)", "tags": [ "commission" ] } }, "/v1/actions/hospitality.action.bind_commission_agreement/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_bind_commission_agreement`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_bind_commission_agreement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "commission_flat_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Per-booking flat commission", "type": "object" }, "commission_kind": { "enum": [ "percent_of_revenue", "per_booking_flat", "per_booking_plus_percent", "none" ], "title": "Commission kind", "type": "string" }, "commission_rate": { "format": "decimal", "title": "Decimal share of commissionable revenue", "type": "string" }, "company_id": { "format": "uuid", "title": "The agent, tour operator, wholesaler or consortium", "type": "string", "x-aerandil-references": "hospitality.company" }, "effective_from": { "format": "date", "title": "First date the terms apply", "type": "string" }, "minimum_payment_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Do not pay this agent below this amount", "type": "object" }, "notes": { "title": "Contract notes", "type": "string" }, "property_id": { "format": "uuid", "title": "Property the terms apply at", "type": "string", "x-aerandil-references": "hospitality.property" }, "tax_treatment": { "enum": [ "standard", "reverse_charge", "exempt" ], "title": "VAT posture of this agent's commission", "type": "string" } }, "required": [ "company_id", "property_id", "effective_from", "commission_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Bind commission agreement (dry-run)", "tags": [ "commission" ] } }, "/v1/actions/hospitality.action.bind_commission_agreement/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_bind_commission_agreement` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.bind_commission_agreement:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_bind_commission_agreement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "commission_flat_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Per-booking flat commission", "type": "object" }, "commission_kind": { "enum": [ "percent_of_revenue", "per_booking_flat", "per_booking_plus_percent", "none" ], "title": "Commission kind", "type": "string" }, "commission_rate": { "format": "decimal", "title": "Decimal share of commissionable revenue", "type": "string" }, "company_id": { "format": "uuid", "title": "The agent, tour operator, wholesaler or consortium", "type": "string", "x-aerandil-references": "hospitality.company" }, "effective_from": { "format": "date", "title": "First date the terms apply", "type": "string" }, "minimum_payment_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Do not pay this agent below this amount", "type": "object" }, "notes": { "title": "Contract notes", "type": "string" }, "property_id": { "format": "uuid", "title": "Property the terms apply at", "type": "string", "x-aerandil-references": "hospitality.property" }, "tax_treatment": { "enum": [ "standard", "reverse_charge", "exempt" ], "title": "VAT posture of this agent's commission", "type": "string" } }, "required": [ "company_id", "property_id", "effective_from", "commission_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Bind commission agreement (rollup delta)", "tags": [ "commission" ] } }, "/v1/actions/hospitality.action.bind_commission_period/apply": { "post": { "description": "Open a new commission period for a (channel, property) and auto-close the prior open period. The pair is the audit ledger; the `current` surface on `channel` is the operator handle for the present row.\n\nEffects: create hospitality.channel_commission_period; modify hospitality.channel_commission_period; modify hospitality.channel; link hospitality.link.channel_commission_period_for_channel; link hospitality.link.channel_commission_period_for_property.", "operationId": "apply_hospitality_action_bind_commission_period", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "channel_id": { "format": "uuid", "title": "Channel", "type": "string", "x-aerandil-references": "hospitality.channel" }, "commission_flat_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Flat per-booking commission", "type": "object" }, "commission_kind": { "enum": [ "percent_of_revenue", "per_booking_flat", "per_booking_plus_percent", "none" ], "title": "Commission kind", "type": "string" }, "commission_rate": { "format": "decimal", "title": "Commission rate", "type": "string" }, "effective_from": { "format": "date", "title": "Effective from", "type": "string" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "channel_id", "property_id", "effective_from", "commission_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.channel_commission_period_for_channel", "hospitality.link.channel_commission_period_for_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.channel_commission_period", "hospitality.channel" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.bind_commission_period:apply" ] } ], "summary": "Bind commission period", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.bind_commission_period/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_bind_commission_period` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.bind_commission_period:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_bind_commission_period", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "channel_id": { "format": "uuid", "title": "Channel", "type": "string", "x-aerandil-references": "hospitality.channel" }, "commission_flat_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Flat per-booking commission", "type": "object" }, "commission_kind": { "enum": [ "percent_of_revenue", "per_booking_flat", "per_booking_plus_percent", "none" ], "title": "Commission kind", "type": "string" }, "commission_rate": { "format": "decimal", "title": "Commission rate", "type": "string" }, "effective_from": { "format": "date", "title": "Effective from", "type": "string" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "channel_id", "property_id", "effective_from", "commission_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.channel_commission_period_for_channel", "hospitality.link.channel_commission_period_for_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.channel_commission_period", "hospitality.channel" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Bind commission period (dry-run)", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.bind_commission_period/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_bind_commission_period`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_bind_commission_period", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "channel_id": { "format": "uuid", "title": "Channel", "type": "string", "x-aerandil-references": "hospitality.channel" }, "commission_flat_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Flat per-booking commission", "type": "object" }, "commission_kind": { "enum": [ "percent_of_revenue", "per_booking_flat", "per_booking_plus_percent", "none" ], "title": "Commission kind", "type": "string" }, "commission_rate": { "format": "decimal", "title": "Commission rate", "type": "string" }, "effective_from": { "format": "date", "title": "Effective from", "type": "string" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "channel_id", "property_id", "effective_from", "commission_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Bind commission period (dry-run)", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.bind_commission_period/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_bind_commission_period` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.bind_commission_period:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_bind_commission_period", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "channel_id": { "format": "uuid", "title": "Channel", "type": "string", "x-aerandil-references": "hospitality.channel" }, "commission_flat_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Flat per-booking commission", "type": "object" }, "commission_kind": { "enum": [ "percent_of_revenue", "per_booking_flat", "per_booking_plus_percent", "none" ], "title": "Commission kind", "type": "string" }, "commission_rate": { "format": "decimal", "title": "Commission rate", "type": "string" }, "effective_from": { "format": "date", "title": "Effective from", "type": "string" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "channel_id", "property_id", "effective_from", "commission_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Bind commission period (rollup delta)", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.bind_comp_authority_policy/apply": { "post": { "description": "Create or update a comp-authority row for (property, role, comp_category). The recovery handler keys on this row when resolving staff comp authority.\n\nEffects: create hospitality.comp_authority_policy; modify hospitality.comp_authority_policy; link hospitality.link.comp_authority_policy_at_property.", "operationId": "apply_hospitality_action_bind_comp_authority_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "comp_category": { "enum": [ "room_night", "food_beverage", "spa", "retail", "parking", "other" ], "title": "Comp category", "type": "string" }, "limit_per_day": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Limit per day", "type": "object" }, "limit_per_incident": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Limit per incident", "type": "object" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "requires_escalation_above": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Soft escalation threshold", "type": "object" }, "role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "Role", "type": "string" } }, "required": [ "property_id", "role", "comp_category" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.comp_authority_policy_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.comp_authority_policy" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.bind_comp_authority_policy:apply" ] } ], "summary": "Bind comp authority policy", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.bind_comp_authority_policy/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_bind_comp_authority_policy` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.bind_comp_authority_policy:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_bind_comp_authority_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "comp_category": { "enum": [ "room_night", "food_beverage", "spa", "retail", "parking", "other" ], "title": "Comp category", "type": "string" }, "limit_per_day": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Limit per day", "type": "object" }, "limit_per_incident": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Limit per incident", "type": "object" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "requires_escalation_above": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Soft escalation threshold", "type": "object" }, "role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "Role", "type": "string" } }, "required": [ "property_id", "role", "comp_category" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.comp_authority_policy_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.comp_authority_policy" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Bind comp authority policy (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.bind_comp_authority_policy/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_bind_comp_authority_policy`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_bind_comp_authority_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "comp_category": { "enum": [ "room_night", "food_beverage", "spa", "retail", "parking", "other" ], "title": "Comp category", "type": "string" }, "limit_per_day": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Limit per day", "type": "object" }, "limit_per_incident": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Limit per incident", "type": "object" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "requires_escalation_above": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Soft escalation threshold", "type": "object" }, "role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "Role", "type": "string" } }, "required": [ "property_id", "role", "comp_category" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Bind comp authority policy (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.bind_comp_authority_policy/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_bind_comp_authority_policy` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.bind_comp_authority_policy:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_bind_comp_authority_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "comp_category": { "enum": [ "room_night", "food_beverage", "spa", "retail", "parking", "other" ], "title": "Comp category", "type": "string" }, "limit_per_day": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Limit per day", "type": "object" }, "limit_per_incident": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Limit per incident", "type": "object" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "requires_escalation_above": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Soft escalation threshold", "type": "object" }, "role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "Role", "type": "string" } }, "required": [ "property_id", "role", "comp_category" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Bind comp authority policy (rollup delta)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.bind_development_pathway_definition/apply": { "post": { "description": "Author or update the ordered progression ladder for a discipline at a property or brand. Keyed on (scope, discipline); subsequent calls with the same key overwrite the ladder. Scope is exactly one of `brand_id` / `property_id`.\n\nEffects: create hospitality.development_pathway_definition; modify hospitality.development_pathway_definition; link hospitality.link.development_pathway_definition_at_brand; link hospitality.link.development_pathway_definition_at_property.", "operationId": "apply_hospitality_action_bind_development_pathway_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "brand_id": { "format": "uuid", "title": "Brand scope (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.brand" }, "discipline": { "enum": [ "front_office", "food_beverage", "culinary", "bar", "housekeeping", "engineering", "spa", "wellness_clinical", "wellness_coaching", "sales", "revenue", "management", "other" ], "title": "Discipline", "type": "string" }, "property_id": { "format": "uuid", "title": "Property scope (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.property" }, "stages": { "items": { "properties": { "code": { "type": "string" }, "display_name": { "type": "string" }, "expected_tenure_years_to_reach": { "format": "decimal", "type": "string" }, "required_certification_kind": { "enum": [ "food_safety_manager", "food_safety_handler", "allergen_awareness", "alcohol_service", "haccp", "sommelier", "wset", "first_aid", "cpr", "pool_lifeguard", "massage_therapy_license", "cosmetology_license", "fire_safety", "other" ], "type": "string" }, "sort_index": { "type": "integer" } }, "required": [ "code", "display_name", "sort_index" ], "type": "object" }, "title": "Ordered pathway stages", "type": "array" } }, "required": [ "discipline", "stages" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.development_pathway_definition_at_brand", "hospitality.link.development_pathway_definition_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.development_pathway_definition" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.bind_development_pathway_definition:apply" ] } ], "summary": "Bind development pathway definition", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.bind_development_pathway_definition/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_bind_development_pathway_definition` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.bind_development_pathway_definition:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_bind_development_pathway_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "brand_id": { "format": "uuid", "title": "Brand scope (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.brand" }, "discipline": { "enum": [ "front_office", "food_beverage", "culinary", "bar", "housekeeping", "engineering", "spa", "wellness_clinical", "wellness_coaching", "sales", "revenue", "management", "other" ], "title": "Discipline", "type": "string" }, "property_id": { "format": "uuid", "title": "Property scope (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.property" }, "stages": { "items": { "properties": { "code": { "type": "string" }, "display_name": { "type": "string" }, "expected_tenure_years_to_reach": { "format": "decimal", "type": "string" }, "required_certification_kind": { "enum": [ "food_safety_manager", "food_safety_handler", "allergen_awareness", "alcohol_service", "haccp", "sommelier", "wset", "first_aid", "cpr", "pool_lifeguard", "massage_therapy_license", "cosmetology_license", "fire_safety", "other" ], "type": "string" }, "sort_index": { "type": "integer" } }, "required": [ "code", "display_name", "sort_index" ], "type": "object" }, "title": "Ordered pathway stages", "type": "array" } }, "required": [ "discipline", "stages" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.development_pathway_definition_at_brand", "hospitality.link.development_pathway_definition_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.development_pathway_definition" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Bind development pathway definition (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.bind_development_pathway_definition/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_bind_development_pathway_definition`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_bind_development_pathway_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "brand_id": { "format": "uuid", "title": "Brand scope (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.brand" }, "discipline": { "enum": [ "front_office", "food_beverage", "culinary", "bar", "housekeeping", "engineering", "spa", "wellness_clinical", "wellness_coaching", "sales", "revenue", "management", "other" ], "title": "Discipline", "type": "string" }, "property_id": { "format": "uuid", "title": "Property scope (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.property" }, "stages": { "items": { "properties": { "code": { "type": "string" }, "display_name": { "type": "string" }, "expected_tenure_years_to_reach": { "format": "decimal", "type": "string" }, "required_certification_kind": { "enum": [ "food_safety_manager", "food_safety_handler", "allergen_awareness", "alcohol_service", "haccp", "sommelier", "wset", "first_aid", "cpr", "pool_lifeguard", "massage_therapy_license", "cosmetology_license", "fire_safety", "other" ], "type": "string" }, "sort_index": { "type": "integer" } }, "required": [ "code", "display_name", "sort_index" ], "type": "object" }, "title": "Ordered pathway stages", "type": "array" } }, "required": [ "discipline", "stages" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Bind development pathway definition (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.bind_development_pathway_definition/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_bind_development_pathway_definition` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.bind_development_pathway_definition:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_bind_development_pathway_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "brand_id": { "format": "uuid", "title": "Brand scope (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.brand" }, "discipline": { "enum": [ "front_office", "food_beverage", "culinary", "bar", "housekeeping", "engineering", "spa", "wellness_clinical", "wellness_coaching", "sales", "revenue", "management", "other" ], "title": "Discipline", "type": "string" }, "property_id": { "format": "uuid", "title": "Property scope (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.property" }, "stages": { "items": { "properties": { "code": { "type": "string" }, "display_name": { "type": "string" }, "expected_tenure_years_to_reach": { "format": "decimal", "type": "string" }, "required_certification_kind": { "enum": [ "food_safety_manager", "food_safety_handler", "allergen_awareness", "alcohol_service", "haccp", "sommelier", "wset", "first_aid", "cpr", "pool_lifeguard", "massage_therapy_license", "cosmetology_license", "fire_safety", "other" ], "type": "string" }, "sort_index": { "type": "integer" } }, "required": [ "code", "display_name", "sort_index" ], "type": "object" }, "title": "Ordered pathway stages", "type": "array" } }, "required": [ "discipline", "stages" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Bind development pathway definition (rollup delta)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.bind_folio_routing_rule/apply": { "post": { "description": "Create or update a folio routing rule between source and target folios at a property. The folio handler walks active rules at charge post-time.\n\nEffects: create hospitality.folio_routing_rule; modify hospitality.folio_routing_rule; link hospitality.link.folio_routing_rule_source; link hospitality.link.folio_routing_rule_target; link hospitality.link.folio_routing_rule_at_property; link hospitality.link.folio_part_of_group_master.", "operationId": "apply_hospitality_action_bind_folio_routing_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "applies_to": { "enum": [ "all", "charge_codes", "charge_categories", "percentage", "capped_amount" ], "title": "Applies to", "type": "string" }, "charge_category_filter": { "items": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "type": "string" }, "title": "Buckets the rule takes (applies_to = charge_categories)", "type": "array" }, "priority": { "title": "Priority", "type": "integer" }, "source_folio_id": { "format": "uuid", "title": "Source folio", "type": "string", "x-aerandil-references": "hospitality.folio" }, "target_folio_id": { "format": "uuid", "title": "Target folio", "type": "string", "x-aerandil-references": "hospitality.folio" } }, "required": [ "source_folio_id", "target_folio_id", "applies_to", "priority" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_routing_rule_source", "hospitality.link.folio_routing_rule_target", "hospitality.link.folio_routing_rule_at_property", "hospitality.link.folio_part_of_group_master" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.folio_routing_rule" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.bind_folio_routing_rule:apply" ] } ], "summary": "Bind folio routing rule", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.bind_folio_routing_rule/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_bind_folio_routing_rule` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.bind_folio_routing_rule:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_bind_folio_routing_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "applies_to": { "enum": [ "all", "charge_codes", "charge_categories", "percentage", "capped_amount" ], "title": "Applies to", "type": "string" }, "charge_category_filter": { "items": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "type": "string" }, "title": "Buckets the rule takes (applies_to = charge_categories)", "type": "array" }, "priority": { "title": "Priority", "type": "integer" }, "source_folio_id": { "format": "uuid", "title": "Source folio", "type": "string", "x-aerandil-references": "hospitality.folio" }, "target_folio_id": { "format": "uuid", "title": "Target folio", "type": "string", "x-aerandil-references": "hospitality.folio" } }, "required": [ "source_folio_id", "target_folio_id", "applies_to", "priority" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_routing_rule_source", "hospitality.link.folio_routing_rule_target", "hospitality.link.folio_routing_rule_at_property", "hospitality.link.folio_part_of_group_master" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.folio_routing_rule" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Bind folio routing rule (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.bind_folio_routing_rule/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_bind_folio_routing_rule`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_bind_folio_routing_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "applies_to": { "enum": [ "all", "charge_codes", "charge_categories", "percentage", "capped_amount" ], "title": "Applies to", "type": "string" }, "charge_category_filter": { "items": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "type": "string" }, "title": "Buckets the rule takes (applies_to = charge_categories)", "type": "array" }, "priority": { "title": "Priority", "type": "integer" }, "source_folio_id": { "format": "uuid", "title": "Source folio", "type": "string", "x-aerandil-references": "hospitality.folio" }, "target_folio_id": { "format": "uuid", "title": "Target folio", "type": "string", "x-aerandil-references": "hospitality.folio" } }, "required": [ "source_folio_id", "target_folio_id", "applies_to", "priority" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Bind folio routing rule (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.bind_folio_routing_rule/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_bind_folio_routing_rule` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.bind_folio_routing_rule:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_bind_folio_routing_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "applies_to": { "enum": [ "all", "charge_codes", "charge_categories", "percentage", "capped_amount" ], "title": "Applies to", "type": "string" }, "charge_category_filter": { "items": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "type": "string" }, "title": "Buckets the rule takes (applies_to = charge_categories)", "type": "array" }, "priority": { "title": "Priority", "type": "integer" }, "source_folio_id": { "format": "uuid", "title": "Source folio", "type": "string", "x-aerandil-references": "hospitality.folio" }, "target_folio_id": { "format": "uuid", "title": "Target folio", "type": "string", "x-aerandil-references": "hospitality.folio" } }, "required": [ "source_folio_id", "target_folio_id", "applies_to", "priority" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Bind folio routing rule (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.bind_ingredient/apply": { "post": { "description": "Create or update an ingredient catalog row keyed on (scope, code). The scope is exactly one of `brand_id` / `property_id`. Subsequent calls with the same (scope, code) update the existing row; allergen + par fields overwrite on update.\n\nEffects: create hospitality.ingredient; modify hospitality.ingredient; link hospitality.link.ingredient_at_brand; link hospitality.link.ingredient_at_property.", "operationId": "apply_hospitality_action_bind_ingredient", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allergen_flags": { "items": { "enum": [ "gluten", "crustaceans", "eggs", "fish", "peanuts", "soybeans", "milk", "nuts", "celery", "mustard", "sesame", "sulphites", "lupin", "molluscs" ], "type": "string" }, "title": "Allergen flags (EU 14 list)", "type": "array" }, "brand_id": { "format": "uuid", "title": "Brand scope (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.brand" }, "category": { "enum": [ "spirit", "wine", "beer", "liqueur", "bitters", "syrup", "juice", "garnish_fruit", "garnish_herb", "dairy", "protein", "produce", "dry_good", "spice", "other" ], "title": "Category", "type": "string" }, "code": { "title": "Operator-assigned SKU / code (natural key)", "type": "string" }, "name": { "title": "Display name", "type": "string" }, "par_quantity": { "format": "decimal", "title": "Par stock level", "type": "string" }, "property_id": { "format": "uuid", "title": "Property scope (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.property" }, "unit_canonical": { "enum": [ "ml", "cl", "oz", "g", "kg", "each", "dash", "drop", "rim", "float", "scoop", "other" ], "title": "Canonical unit", "type": "string" } }, "required": [ "code", "name", "category", "unit_canonical" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.ingredient_at_brand", "hospitality.link.ingredient_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.ingredient" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.bind_ingredient:apply" ] } ], "summary": "Bind ingredient", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.bind_ingredient/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_bind_ingredient` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.bind_ingredient:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_bind_ingredient", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allergen_flags": { "items": { "enum": [ "gluten", "crustaceans", "eggs", "fish", "peanuts", "soybeans", "milk", "nuts", "celery", "mustard", "sesame", "sulphites", "lupin", "molluscs" ], "type": "string" }, "title": "Allergen flags (EU 14 list)", "type": "array" }, "brand_id": { "format": "uuid", "title": "Brand scope (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.brand" }, "category": { "enum": [ "spirit", "wine", "beer", "liqueur", "bitters", "syrup", "juice", "garnish_fruit", "garnish_herb", "dairy", "protein", "produce", "dry_good", "spice", "other" ], "title": "Category", "type": "string" }, "code": { "title": "Operator-assigned SKU / code (natural key)", "type": "string" }, "name": { "title": "Display name", "type": "string" }, "par_quantity": { "format": "decimal", "title": "Par stock level", "type": "string" }, "property_id": { "format": "uuid", "title": "Property scope (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.property" }, "unit_canonical": { "enum": [ "ml", "cl", "oz", "g", "kg", "each", "dash", "drop", "rim", "float", "scoop", "other" ], "title": "Canonical unit", "type": "string" } }, "required": [ "code", "name", "category", "unit_canonical" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.ingredient_at_brand", "hospitality.link.ingredient_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.ingredient" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Bind ingredient (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.bind_ingredient/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_bind_ingredient`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_bind_ingredient", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allergen_flags": { "items": { "enum": [ "gluten", "crustaceans", "eggs", "fish", "peanuts", "soybeans", "milk", "nuts", "celery", "mustard", "sesame", "sulphites", "lupin", "molluscs" ], "type": "string" }, "title": "Allergen flags (EU 14 list)", "type": "array" }, "brand_id": { "format": "uuid", "title": "Brand scope (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.brand" }, "category": { "enum": [ "spirit", "wine", "beer", "liqueur", "bitters", "syrup", "juice", "garnish_fruit", "garnish_herb", "dairy", "protein", "produce", "dry_good", "spice", "other" ], "title": "Category", "type": "string" }, "code": { "title": "Operator-assigned SKU / code (natural key)", "type": "string" }, "name": { "title": "Display name", "type": "string" }, "par_quantity": { "format": "decimal", "title": "Par stock level", "type": "string" }, "property_id": { "format": "uuid", "title": "Property scope (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.property" }, "unit_canonical": { "enum": [ "ml", "cl", "oz", "g", "kg", "each", "dash", "drop", "rim", "float", "scoop", "other" ], "title": "Canonical unit", "type": "string" } }, "required": [ "code", "name", "category", "unit_canonical" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Bind ingredient (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.bind_ingredient/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_bind_ingredient` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.bind_ingredient:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_bind_ingredient", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allergen_flags": { "items": { "enum": [ "gluten", "crustaceans", "eggs", "fish", "peanuts", "soybeans", "milk", "nuts", "celery", "mustard", "sesame", "sulphites", "lupin", "molluscs" ], "type": "string" }, "title": "Allergen flags (EU 14 list)", "type": "array" }, "brand_id": { "format": "uuid", "title": "Brand scope (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.brand" }, "category": { "enum": [ "spirit", "wine", "beer", "liqueur", "bitters", "syrup", "juice", "garnish_fruit", "garnish_herb", "dairy", "protein", "produce", "dry_good", "spice", "other" ], "title": "Category", "type": "string" }, "code": { "title": "Operator-assigned SKU / code (natural key)", "type": "string" }, "name": { "title": "Display name", "type": "string" }, "par_quantity": { "format": "decimal", "title": "Par stock level", "type": "string" }, "property_id": { "format": "uuid", "title": "Property scope (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.property" }, "unit_canonical": { "enum": [ "ml", "cl", "oz", "g", "kg", "each", "dash", "drop", "rim", "float", "scoop", "other" ], "title": "Canonical unit", "type": "string" } }, "required": [ "code", "name", "category", "unit_canonical" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Bind ingredient (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.bind_recipe/apply": { "post": { "description": "Create or update a recipe and its `recipe_for_service_item` link. Authoritative producer-side spec; the cache fields (`sell_price`, `pour_cost`) populate from associated refreshes.\n\nEffects: create hospitality.recipe; modify hospitality.recipe; link hospitality.link.recipe_for_service_item.", "operationId": "apply_hospitality_action_bind_recipe", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "recipe_kind": { "enum": [ "drink_cocktail", "drink_coffee", "drink_tea", "drink_wine_pour", "dish_main", "dish_side", "dish_dessert", "dish_amuse", "spa_treatment_protocol", "other" ], "title": "Recipe kind", "type": "string" }, "service_item_id": { "format": "uuid", "title": "Service item", "type": "string", "x-aerandil-references": "hospitality.service_item" } }, "required": [ "service_item_id", "recipe_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.recipe_for_service_item" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.recipe" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.bind_recipe:apply" ] } ], "summary": "Bind recipe", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.bind_recipe/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_bind_recipe` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.bind_recipe:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_bind_recipe", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "recipe_kind": { "enum": [ "drink_cocktail", "drink_coffee", "drink_tea", "drink_wine_pour", "dish_main", "dish_side", "dish_dessert", "dish_amuse", "spa_treatment_protocol", "other" ], "title": "Recipe kind", "type": "string" }, "service_item_id": { "format": "uuid", "title": "Service item", "type": "string", "x-aerandil-references": "hospitality.service_item" } }, "required": [ "service_item_id", "recipe_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.recipe_for_service_item" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.recipe" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Bind recipe (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.bind_recipe/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_bind_recipe`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_bind_recipe", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "recipe_kind": { "enum": [ "drink_cocktail", "drink_coffee", "drink_tea", "drink_wine_pour", "dish_main", "dish_side", "dish_dessert", "dish_amuse", "spa_treatment_protocol", "other" ], "title": "Recipe kind", "type": "string" }, "service_item_id": { "format": "uuid", "title": "Service item", "type": "string", "x-aerandil-references": "hospitality.service_item" } }, "required": [ "service_item_id", "recipe_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Bind recipe (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.bind_recipe/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_bind_recipe` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.bind_recipe:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_bind_recipe", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "recipe_kind": { "enum": [ "drink_cocktail", "drink_coffee", "drink_tea", "drink_wine_pour", "dish_main", "dish_side", "dish_dessert", "dish_amuse", "spa_treatment_protocol", "other" ], "title": "Recipe kind", "type": "string" }, "service_item_id": { "format": "uuid", "title": "Service item", "type": "string", "x-aerandil-references": "hospitality.service_item" } }, "required": [ "service_item_id", "recipe_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Bind recipe (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.block_agent_registry_entry/apply": { "post": { "description": "Security kill switch: mark a registry entry `blocked` AND disable every live installation of it in the same transaction (status `disabled`, the system-driven not-running state) — the VS Code Marketplace block precedent, where a malicious extension is force-disabled on existing installs, not just delisted. Emits `agent_registry_entry.blocked` plus one `agent_installation.disabled` per affected installation.\n\nEffects: modify hospitality.agent_registry_entry; modify hospitality.agent_installation.", "operationId": "apply_hospitality_action_block_agent_registry_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the entry is blocked (security rationale)", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_registry_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.agent_registry_entry", "hospitality.agent_installation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.block_agent_registry_entry:apply" ] } ], "summary": "Block agent registry entry", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.block_agent_registry_entry/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_block_agent_registry_entry` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.block_agent_registry_entry:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_block_agent_registry_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the entry is blocked (security rationale)", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_registry_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.agent_registry_entry", "hospitality.agent_installation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Block agent registry entry (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.block_agent_registry_entry/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_block_agent_registry_entry`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_block_agent_registry_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the entry is blocked (security rationale)", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_registry_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Block agent registry entry (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.block_agent_registry_entry/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_block_agent_registry_entry` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.block_agent_registry_entry:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_block_agent_registry_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the entry is blocked (security rationale)", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_registry_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Block agent registry entry (rollup delta)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.block_housekeeping_task/apply": { "post": { "description": "A typed obstacle stands between the attendant and the room — do-not-disturb, guest in room, access refused. The task stays on the board with the reason attached, expecting a retry (start_housekeeping_task) or a deliberate skip; it never silently vanishes into an attendant's memory.\n\nEffects: modify hospitality.housekeeping_task.", "operationId": "apply_hospitality_action_block_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "block_reason": { "enum": [ "do_not_disturb", "guest_in_room", "access_refused", "maintenance_required", "other" ], "title": "What stands in the way", "type": "string" }, "notes": { "title": "Detail for the retry", "type": "string" } }, "required": [ "block_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.block_housekeeping_task:apply" ] } ], "summary": "Block housekeeping task", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.block_housekeeping_task/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_block_housekeeping_task` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.block_housekeeping_task:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_block_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "block_reason": { "enum": [ "do_not_disturb", "guest_in_room", "access_refused", "maintenance_required", "other" ], "title": "What stands in the way", "type": "string" }, "notes": { "title": "Detail for the retry", "type": "string" } }, "required": [ "block_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Block housekeeping task (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.block_housekeeping_task/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_block_housekeeping_task`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_block_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "block_reason": { "enum": [ "do_not_disturb", "guest_in_room", "access_refused", "maintenance_required", "other" ], "title": "What stands in the way", "type": "string" }, "notes": { "title": "Detail for the retry", "type": "string" } }, "required": [ "block_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Block housekeeping task (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.block_housekeeping_task/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_block_housekeeping_task` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.block_housekeeping_task:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_block_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "block_reason": { "enum": [ "do_not_disturb", "guest_in_room", "access_refused", "maintenance_required", "other" ], "title": "What stands in the way", "type": "string" }, "notes": { "title": "Detail for the retry", "type": "string" } }, "required": [ "block_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Block housekeeping task (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.block_work_order/apply": { "post": { "description": "The work is waiting on something outside the engineer's control — parts on order, a contractor, guest access. The order stays on the board with the reason attached; schedule_work_order or start_work_order is the resume.\n\nEffects: modify hospitality.work_order.", "operationId": "apply_hospitality_action_block_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "What the work is waiting on", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.work_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.block_work_order:apply" ] } ], "summary": "Block work order", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.block_work_order/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_block_work_order` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.block_work_order:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_block_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "What the work is waiting on", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.work_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Block work order (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.block_work_order/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_block_work_order`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_block_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "What the work is waiting on", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Block work order (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.block_work_order/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_block_work_order` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.block_work_order:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_block_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "What the work is waiting on", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Block work order (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.book_appointment/apply": { "post": { "description": "Book a timed service: one guest × one service in a time window. Snapshots price, duration, and the pre/cleanup buffer pair from the spa_service at booking (catalogue edits never rewrite booking history); `duration_minutes` and `price` parameters override the snapshot for skill-level or yield-priced bookings (Book4Time price scaling). Conflict checks: the room admits at most `capacity` overlapping appointments over the buffered window [start - pre_time, end + cleanup_time]; a provider is single-booked over the same window. The capability maps (treatment_room_supports_service, staff_performs_spa_service) are enforced only when the resource declares at least one row. A service bound to a wellness_modality with requires_medical_licensing = true requires `external_record_reference_id` (the 0005 clinical seam). Business time: `booked_at` is when the booking was taken (defaults to now); replayed histories pass it explicitly so pace/lead-time reads derive correctly. A present `external_ref` routes the create through the appointment_external_ref business key, making a crashed-pass retry a replay instead of a duplicate booking. A couples service is two appointments sharing a capacity-2 room. Emits `spa.appointment_booked`.\n\nEffects: create hospitality.appointment; link hospitality.link.appointment_for_service; link hospitality.link.appointment_at_outlet; link hospitality.link.appointment_in_treatment_room; link hospitality.link.appointment_with_provider; link hospitality.link.appointment_for_person; link hospitality.link.appointment_references_external_record.", "operationId": "apply_hospitality_action_book_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "booked_at": { "format": "date-time", "title": "When the booking was taken — business time, not record time (defaults to now)", "type": "string" }, "duration_minutes": { "title": "Duration override in minutes (skill-level / guest-specific duration)", "type": "integer" }, "external_record_reference_id": { "format": "uuid", "title": "Clinical-record reference (mandatory when the bound modality requires_medical_licensing)", "type": "string", "x-aerandil-references": "hospitality.external_record_reference" }, "external_ref": { "title": "Source-system key for replayed / connector-landed bookings", "type": "string" }, "guest_kind": { "enum": [ "hotel_guest", "member", "external" ], "title": "Who the client is to the property (in-house capture dimension)", "type": "string" }, "notes": { "title": "Front-desk / therapist notes (may carry intake detail)", "type": "string" }, "outlet_id": { "format": "uuid", "title": "Outlet the appointment trades under", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "person_id": { "format": "uuid", "title": "Guest the appointment is for (optional — desk walk-ins may book anonymously)", "type": "string", "x-aerandil-references": "hospitality.person" }, "price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Price override (skill-level / yield pricing; defaults to the service's list price)", "type": "object" }, "provider_id": { "format": "uuid", "title": "Provider / therapist (optional — may be assigned later via reschedule)", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "room_id": { "format": "uuid", "title": "Treatment room (optional — may be assigned later via reschedule)", "type": "string", "x-aerandil-references": "hospitality.treatment_room" }, "service_id": { "format": "uuid", "title": "Service being booked", "type": "string", "x-aerandil-references": "hospitality.spa_service" }, "start_at": { "format": "date-time", "title": "Treatment start", "type": "string" } }, "required": [ "service_id", "outlet_id", "start_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.appointment_for_service", "hospitality.link.appointment_at_outlet", "hospitality.link.appointment_in_treatment_room", "hospitality.link.appointment_with_provider", "hospitality.link.appointment_for_person", "hospitality.link.appointment_references_external_record" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.appointment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.book_appointment:apply" ] } ], "summary": "Book appointment", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.book_appointment/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_book_appointment` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.book_appointment:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_book_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "booked_at": { "format": "date-time", "title": "When the booking was taken — business time, not record time (defaults to now)", "type": "string" }, "duration_minutes": { "title": "Duration override in minutes (skill-level / guest-specific duration)", "type": "integer" }, "external_record_reference_id": { "format": "uuid", "title": "Clinical-record reference (mandatory when the bound modality requires_medical_licensing)", "type": "string", "x-aerandil-references": "hospitality.external_record_reference" }, "external_ref": { "title": "Source-system key for replayed / connector-landed bookings", "type": "string" }, "guest_kind": { "enum": [ "hotel_guest", "member", "external" ], "title": "Who the client is to the property (in-house capture dimension)", "type": "string" }, "notes": { "title": "Front-desk / therapist notes (may carry intake detail)", "type": "string" }, "outlet_id": { "format": "uuid", "title": "Outlet the appointment trades under", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "person_id": { "format": "uuid", "title": "Guest the appointment is for (optional — desk walk-ins may book anonymously)", "type": "string", "x-aerandil-references": "hospitality.person" }, "price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Price override (skill-level / yield pricing; defaults to the service's list price)", "type": "object" }, "provider_id": { "format": "uuid", "title": "Provider / therapist (optional — may be assigned later via reschedule)", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "room_id": { "format": "uuid", "title": "Treatment room (optional — may be assigned later via reschedule)", "type": "string", "x-aerandil-references": "hospitality.treatment_room" }, "service_id": { "format": "uuid", "title": "Service being booked", "type": "string", "x-aerandil-references": "hospitality.spa_service" }, "start_at": { "format": "date-time", "title": "Treatment start", "type": "string" } }, "required": [ "service_id", "outlet_id", "start_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.appointment_for_service", "hospitality.link.appointment_at_outlet", "hospitality.link.appointment_in_treatment_room", "hospitality.link.appointment_with_provider", "hospitality.link.appointment_for_person", "hospitality.link.appointment_references_external_record" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.appointment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Book appointment (dry-run)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.book_appointment/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_book_appointment`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_book_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "booked_at": { "format": "date-time", "title": "When the booking was taken — business time, not record time (defaults to now)", "type": "string" }, "duration_minutes": { "title": "Duration override in minutes (skill-level / guest-specific duration)", "type": "integer" }, "external_record_reference_id": { "format": "uuid", "title": "Clinical-record reference (mandatory when the bound modality requires_medical_licensing)", "type": "string", "x-aerandil-references": "hospitality.external_record_reference" }, "external_ref": { "title": "Source-system key for replayed / connector-landed bookings", "type": "string" }, "guest_kind": { "enum": [ "hotel_guest", "member", "external" ], "title": "Who the client is to the property (in-house capture dimension)", "type": "string" }, "notes": { "title": "Front-desk / therapist notes (may carry intake detail)", "type": "string" }, "outlet_id": { "format": "uuid", "title": "Outlet the appointment trades under", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "person_id": { "format": "uuid", "title": "Guest the appointment is for (optional — desk walk-ins may book anonymously)", "type": "string", "x-aerandil-references": "hospitality.person" }, "price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Price override (skill-level / yield pricing; defaults to the service's list price)", "type": "object" }, "provider_id": { "format": "uuid", "title": "Provider / therapist (optional — may be assigned later via reschedule)", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "room_id": { "format": "uuid", "title": "Treatment room (optional — may be assigned later via reschedule)", "type": "string", "x-aerandil-references": "hospitality.treatment_room" }, "service_id": { "format": "uuid", "title": "Service being booked", "type": "string", "x-aerandil-references": "hospitality.spa_service" }, "start_at": { "format": "date-time", "title": "Treatment start", "type": "string" } }, "required": [ "service_id", "outlet_id", "start_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Book appointment (dry-run)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.book_appointment/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_book_appointment` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.book_appointment:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_book_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "booked_at": { "format": "date-time", "title": "When the booking was taken — business time, not record time (defaults to now)", "type": "string" }, "duration_minutes": { "title": "Duration override in minutes (skill-level / guest-specific duration)", "type": "integer" }, "external_record_reference_id": { "format": "uuid", "title": "Clinical-record reference (mandatory when the bound modality requires_medical_licensing)", "type": "string", "x-aerandil-references": "hospitality.external_record_reference" }, "external_ref": { "title": "Source-system key for replayed / connector-landed bookings", "type": "string" }, "guest_kind": { "enum": [ "hotel_guest", "member", "external" ], "title": "Who the client is to the property (in-house capture dimension)", "type": "string" }, "notes": { "title": "Front-desk / therapist notes (may carry intake detail)", "type": "string" }, "outlet_id": { "format": "uuid", "title": "Outlet the appointment trades under", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "person_id": { "format": "uuid", "title": "Guest the appointment is for (optional — desk walk-ins may book anonymously)", "type": "string", "x-aerandil-references": "hospitality.person" }, "price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Price override (skill-level / yield pricing; defaults to the service's list price)", "type": "object" }, "provider_id": { "format": "uuid", "title": "Provider / therapist (optional — may be assigned later via reschedule)", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "room_id": { "format": "uuid", "title": "Treatment room (optional — may be assigned later via reschedule)", "type": "string", "x-aerandil-references": "hospitality.treatment_room" }, "service_id": { "format": "uuid", "title": "Service being booked", "type": "string", "x-aerandil-references": "hospitality.spa_service" }, "start_at": { "format": "date-time", "title": "Treatment start", "type": "string" } }, "required": [ "service_id", "outlet_id", "start_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Book appointment (rollup delta)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.book_function_event/apply": { "post": { "description": "Book one use of a function space: a window on a date, a setup style, and the expected attendance, `tentative` unless asked for `definite`. Refused when the space (or its combined room, or any of its sections) already has a live event overlapping the setup-to-teardown window, when the space is not active, or when the expected count exceeds the room's capacity in that style. A `group_block_id` makes it the group's event; charges then post to the block's master folio by default.\n\nEffects: create hospitality.function_event; link hospitality.link.function_event_at_property; link hospitality.link.function_event_in_space; link hospitality.link.function_event_for_block; link hospitality.link.function_event_contact.", "operationId": "apply_hospitality_action_book_function_event", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "contact_person_id": { "format": "uuid", "title": "The client's on-site contact", "type": "string", "x-aerandil-references": "hospitality.person" }, "do_not_move": { "title": "The client was promised this room (default false)", "type": "boolean" }, "end_at": { "format": "date-time", "title": "Doors close", "type": "string" }, "event_date": { "format": "date", "title": "The property-local day", "type": "string" }, "event_type": { "enum": [ "meeting", "conference", "breakout", "reception", "breakfast", "lunch", "dinner", "banquet", "wedding_ceremony", "wedding_breakfast", "exhibition", "rehearsal", "other" ], "title": "What kind of function", "type": "string" }, "expected_count": { "title": "Expected attendance", "type": "integer" }, "function_space_id": { "format": "uuid", "title": "The space to set it in", "type": "string", "x-aerandil-references": "hospitality.function_space" }, "group_block_id": { "format": "uuid", "title": "The group block this is an event of", "type": "string", "x-aerandil-references": "hospitality.group_block" }, "guarantee_due_at": { "format": "date-time", "title": "When the guarantee is due", "type": "string" }, "guaranteed_count": { "title": "Guaranteed attendance, when already given", "type": "integer" }, "name": { "title": "Event name", "type": "string" }, "notes": { "title": "Notes for the operating departments", "type": "string" }, "rental": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Function space rental agreed", "type": "object" }, "setup_from": { "format": "date-time", "title": "When the setup crew may have the room", "type": "string" }, "setup_style": { "enum": [ "theatre", "classroom", "boardroom", "u_shape", "hollow_square", "banquet_rounds", "cabaret", "reception", "exhibition", "existing" ], "title": "How the room is set", "type": "string" }, "start_at": { "format": "date-time", "title": "Doors open", "type": "string" }, "status": { "enum": [ "tentative", "definite" ], "title": "tentative (default) or definite", "type": "string" }, "teardown_until": { "format": "date-time", "title": "When the room must be clear again", "type": "string" } }, "required": [ "name", "event_type", "function_space_id", "event_date", "start_at", "end_at", "setup_style", "expected_count" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.function_event_at_property", "hospitality.link.function_event_in_space", "hospitality.link.function_event_for_block", "hospitality.link.function_event_contact" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.function_event" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.book_function_event:apply" ] } ], "summary": "Book function event", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.book_function_event/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_book_function_event` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.book_function_event:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_book_function_event", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "contact_person_id": { "format": "uuid", "title": "The client's on-site contact", "type": "string", "x-aerandil-references": "hospitality.person" }, "do_not_move": { "title": "The client was promised this room (default false)", "type": "boolean" }, "end_at": { "format": "date-time", "title": "Doors close", "type": "string" }, "event_date": { "format": "date", "title": "The property-local day", "type": "string" }, "event_type": { "enum": [ "meeting", "conference", "breakout", "reception", "breakfast", "lunch", "dinner", "banquet", "wedding_ceremony", "wedding_breakfast", "exhibition", "rehearsal", "other" ], "title": "What kind of function", "type": "string" }, "expected_count": { "title": "Expected attendance", "type": "integer" }, "function_space_id": { "format": "uuid", "title": "The space to set it in", "type": "string", "x-aerandil-references": "hospitality.function_space" }, "group_block_id": { "format": "uuid", "title": "The group block this is an event of", "type": "string", "x-aerandil-references": "hospitality.group_block" }, "guarantee_due_at": { "format": "date-time", "title": "When the guarantee is due", "type": "string" }, "guaranteed_count": { "title": "Guaranteed attendance, when already given", "type": "integer" }, "name": { "title": "Event name", "type": "string" }, "notes": { "title": "Notes for the operating departments", "type": "string" }, "rental": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Function space rental agreed", "type": "object" }, "setup_from": { "format": "date-time", "title": "When the setup crew may have the room", "type": "string" }, "setup_style": { "enum": [ "theatre", "classroom", "boardroom", "u_shape", "hollow_square", "banquet_rounds", "cabaret", "reception", "exhibition", "existing" ], "title": "How the room is set", "type": "string" }, "start_at": { "format": "date-time", "title": "Doors open", "type": "string" }, "status": { "enum": [ "tentative", "definite" ], "title": "tentative (default) or definite", "type": "string" }, "teardown_until": { "format": "date-time", "title": "When the room must be clear again", "type": "string" } }, "required": [ "name", "event_type", "function_space_id", "event_date", "start_at", "end_at", "setup_style", "expected_count" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.function_event_at_property", "hospitality.link.function_event_in_space", "hospitality.link.function_event_for_block", "hospitality.link.function_event_contact" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.function_event" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Book function event (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.book_function_event/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_book_function_event`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_book_function_event", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "contact_person_id": { "format": "uuid", "title": "The client's on-site contact", "type": "string", "x-aerandil-references": "hospitality.person" }, "do_not_move": { "title": "The client was promised this room (default false)", "type": "boolean" }, "end_at": { "format": "date-time", "title": "Doors close", "type": "string" }, "event_date": { "format": "date", "title": "The property-local day", "type": "string" }, "event_type": { "enum": [ "meeting", "conference", "breakout", "reception", "breakfast", "lunch", "dinner", "banquet", "wedding_ceremony", "wedding_breakfast", "exhibition", "rehearsal", "other" ], "title": "What kind of function", "type": "string" }, "expected_count": { "title": "Expected attendance", "type": "integer" }, "function_space_id": { "format": "uuid", "title": "The space to set it in", "type": "string", "x-aerandil-references": "hospitality.function_space" }, "group_block_id": { "format": "uuid", "title": "The group block this is an event of", "type": "string", "x-aerandil-references": "hospitality.group_block" }, "guarantee_due_at": { "format": "date-time", "title": "When the guarantee is due", "type": "string" }, "guaranteed_count": { "title": "Guaranteed attendance, when already given", "type": "integer" }, "name": { "title": "Event name", "type": "string" }, "notes": { "title": "Notes for the operating departments", "type": "string" }, "rental": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Function space rental agreed", "type": "object" }, "setup_from": { "format": "date-time", "title": "When the setup crew may have the room", "type": "string" }, "setup_style": { "enum": [ "theatre", "classroom", "boardroom", "u_shape", "hollow_square", "banquet_rounds", "cabaret", "reception", "exhibition", "existing" ], "title": "How the room is set", "type": "string" }, "start_at": { "format": "date-time", "title": "Doors open", "type": "string" }, "status": { "enum": [ "tentative", "definite" ], "title": "tentative (default) or definite", "type": "string" }, "teardown_until": { "format": "date-time", "title": "When the room must be clear again", "type": "string" } }, "required": [ "name", "event_type", "function_space_id", "event_date", "start_at", "end_at", "setup_style", "expected_count" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Book function event (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.book_function_event/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_book_function_event` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.book_function_event:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_book_function_event", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "contact_person_id": { "format": "uuid", "title": "The client's on-site contact", "type": "string", "x-aerandil-references": "hospitality.person" }, "do_not_move": { "title": "The client was promised this room (default false)", "type": "boolean" }, "end_at": { "format": "date-time", "title": "Doors close", "type": "string" }, "event_date": { "format": "date", "title": "The property-local day", "type": "string" }, "event_type": { "enum": [ "meeting", "conference", "breakout", "reception", "breakfast", "lunch", "dinner", "banquet", "wedding_ceremony", "wedding_breakfast", "exhibition", "rehearsal", "other" ], "title": "What kind of function", "type": "string" }, "expected_count": { "title": "Expected attendance", "type": "integer" }, "function_space_id": { "format": "uuid", "title": "The space to set it in", "type": "string", "x-aerandil-references": "hospitality.function_space" }, "group_block_id": { "format": "uuid", "title": "The group block this is an event of", "type": "string", "x-aerandil-references": "hospitality.group_block" }, "guarantee_due_at": { "format": "date-time", "title": "When the guarantee is due", "type": "string" }, "guaranteed_count": { "title": "Guaranteed attendance, when already given", "type": "integer" }, "name": { "title": "Event name", "type": "string" }, "notes": { "title": "Notes for the operating departments", "type": "string" }, "rental": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Function space rental agreed", "type": "object" }, "setup_from": { "format": "date-time", "title": "When the setup crew may have the room", "type": "string" }, "setup_style": { "enum": [ "theatre", "classroom", "boardroom", "u_shape", "hollow_square", "banquet_rounds", "cabaret", "reception", "exhibition", "existing" ], "title": "How the room is set", "type": "string" }, "start_at": { "format": "date-time", "title": "Doors open", "type": "string" }, "status": { "enum": [ "tentative", "definite" ], "title": "tentative (default) or definite", "type": "string" }, "teardown_until": { "format": "date-time", "title": "When the room must be clear again", "type": "string" } }, "required": [ "name", "event_type", "function_space_id", "event_date", "start_at", "end_at", "setup_style", "expected_count" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Book function event (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.book_modality_session/apply": { "post": { "description": "Book a wellness-modality session for the target membership. For clinical modalities (`requires_medical_licensing = true`), the matching `external_record_reference_id` parameter is mandatory at action-time — the handler rejects the booking otherwise. Non-clinical modalities (cold/heat/contrast therapy, resistance training, recovery, mindfulness, sleep work) book without the clinical-seam parameter.\n\nEffects: create hospitality.venue_visit; link hospitality.link.venue_visit_at_venue; link hospitality.link.venue_visit_for_person; link hospitality.link.venue_visit_for_modality; link hospitality.link.venue_visit_references_external_record.", "operationId": "apply_hospitality_action_book_modality_session", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "external_record_reference_id": { "format": "uuid", "title": "Clinical-record reference (mandatory when modality requires_medical_licensing)", "type": "string", "x-aerandil-references": "hospitality.external_record_reference" }, "modality_id": { "format": "uuid", "title": "Modality being booked", "type": "string", "x-aerandil-references": "hospitality.wellness_modality" }, "scheduled_at": { "format": "date-time", "title": "Session start time", "type": "string" }, "venue_id": { "format": "uuid", "title": "Venue where the session is booked", "type": "string", "x-aerandil-references": "hospitality.venue" } }, "required": [ "modality_id", "venue_id", "scheduled_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.venue_visit_at_venue", "hospitality.link.venue_visit_for_person", "hospitality.link.venue_visit_for_modality", "hospitality.link.venue_visit_references_external_record" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.venue_visit" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.book_modality_session:apply" ] } ], "summary": "Book modality session", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.book_modality_session/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_book_modality_session` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.book_modality_session:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_book_modality_session", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "external_record_reference_id": { "format": "uuid", "title": "Clinical-record reference (mandatory when modality requires_medical_licensing)", "type": "string", "x-aerandil-references": "hospitality.external_record_reference" }, "modality_id": { "format": "uuid", "title": "Modality being booked", "type": "string", "x-aerandil-references": "hospitality.wellness_modality" }, "scheduled_at": { "format": "date-time", "title": "Session start time", "type": "string" }, "venue_id": { "format": "uuid", "title": "Venue where the session is booked", "type": "string", "x-aerandil-references": "hospitality.venue" } }, "required": [ "modality_id", "venue_id", "scheduled_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.venue_visit_at_venue", "hospitality.link.venue_visit_for_person", "hospitality.link.venue_visit_for_modality", "hospitality.link.venue_visit_references_external_record" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.venue_visit" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Book modality session (dry-run)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.book_modality_session/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_book_modality_session`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_book_modality_session", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "external_record_reference_id": { "format": "uuid", "title": "Clinical-record reference (mandatory when modality requires_medical_licensing)", "type": "string", "x-aerandil-references": "hospitality.external_record_reference" }, "modality_id": { "format": "uuid", "title": "Modality being booked", "type": "string", "x-aerandil-references": "hospitality.wellness_modality" }, "scheduled_at": { "format": "date-time", "title": "Session start time", "type": "string" }, "venue_id": { "format": "uuid", "title": "Venue where the session is booked", "type": "string", "x-aerandil-references": "hospitality.venue" } }, "required": [ "modality_id", "venue_id", "scheduled_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Book modality session (dry-run)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.book_modality_session/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_book_modality_session` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.book_modality_session:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_book_modality_session", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "external_record_reference_id": { "format": "uuid", "title": "Clinical-record reference (mandatory when modality requires_medical_licensing)", "type": "string", "x-aerandil-references": "hospitality.external_record_reference" }, "modality_id": { "format": "uuid", "title": "Modality being booked", "type": "string", "x-aerandil-references": "hospitality.wellness_modality" }, "scheduled_at": { "format": "date-time", "title": "Session start time", "type": "string" }, "venue_id": { "format": "uuid", "title": "Venue where the session is booked", "type": "string", "x-aerandil-references": "hospitality.venue" } }, "required": [ "modality_id", "venue_id", "scheduled_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Book modality session (rollup delta)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.bump_ticket/apply": { "post": { "description": "Station-side fulfilment: the ticket leaves the board (`bumped`, timestamped) and its lines move to `fulfilled`. Voided / comped lines on the ticket are left as they are. Idempotent on an already-bumped ticket. Emits `fnb.ticket_bumped`.\n\nEffects: modify hospitality.kitchen_ticket; modify hospitality.check_line.", "operationId": "apply_hospitality_action_bump_ticket", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "bumped_at": { "format": "date-time", "title": "When the station bumped the ticket — business time for replayed histories (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.kitchen_ticket" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.kitchen_ticket", "hospitality.check_line" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.bump_ticket:apply" ] } ], "summary": "Bump ticket", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.bump_ticket/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_bump_ticket` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.bump_ticket:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_bump_ticket", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "bumped_at": { "format": "date-time", "title": "When the station bumped the ticket — business time for replayed histories (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.kitchen_ticket" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.kitchen_ticket", "hospitality.check_line" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Bump ticket (dry-run)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.bump_ticket/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_bump_ticket`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_bump_ticket", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "bumped_at": { "format": "date-time", "title": "When the station bumped the ticket — business time for replayed histories (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.kitchen_ticket" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Bump ticket (dry-run)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.bump_ticket/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_bump_ticket` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.bump_ticket:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_bump_ticket", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "bumped_at": { "format": "date-time", "title": "When the station bumped the ticket — business time for replayed histories (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.kitchen_ticket" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Bump ticket (rollup delta)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.cancel_appointment/apply": { "post": { "description": "Cancel a not-yet-started appointment, typed at cancel time (Mangomint's normal / late split plus operator cancellations): `guest` is an in-policy guest cancellation, `late` is inside the property's late-cancel window, `operator` is a property-side cancellation (therapist sick, room out of service). Fee posting is deliberately not automated (Book4Time posture — deposits and discretionary charging); a late-cancel fee is an operator post_charge. Business time: `cancelled_at` defaults to now. Cancelling a cancelled appointment is a no-op. Emits `spa.appointment_cancelled`.\n\nEffects: modify hospitality.appointment.", "operationId": "apply_hospitality_action_cancel_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancellation_kind": { "enum": [ "guest", "late", "operator" ], "title": "Cancellation kind (guest / late / operator)", "type": "string" }, "cancelled_at": { "format": "date-time", "title": "When the cancellation was taken (defaults to now)", "type": "string" } }, "required": [ "cancellation_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.appointment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.cancel_appointment:apply" ] } ], "summary": "Cancel appointment", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.cancel_appointment/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_cancel_appointment` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.cancel_appointment:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_cancel_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancellation_kind": { "enum": [ "guest", "late", "operator" ], "title": "Cancellation kind (guest / late / operator)", "type": "string" }, "cancelled_at": { "format": "date-time", "title": "When the cancellation was taken (defaults to now)", "type": "string" } }, "required": [ "cancellation_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.appointment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Cancel appointment (dry-run)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.cancel_appointment/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_cancel_appointment`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_cancel_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancellation_kind": { "enum": [ "guest", "late", "operator" ], "title": "Cancellation kind (guest / late / operator)", "type": "string" }, "cancelled_at": { "format": "date-time", "title": "When the cancellation was taken (defaults to now)", "type": "string" } }, "required": [ "cancellation_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Cancel appointment (dry-run)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.cancel_appointment/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_cancel_appointment` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.cancel_appointment:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_cancel_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancellation_kind": { "enum": [ "guest", "late", "operator" ], "title": "Cancellation kind (guest / late / operator)", "type": "string" }, "cancelled_at": { "format": "date-time", "title": "When the cancellation was taken (defaults to now)", "type": "string" } }, "required": [ "cancellation_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Cancel appointment (rollup delta)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.cancel_banquet_event_order/apply": { "post": { "description": "Withdraw the order: `draft`, `issued` or `revised` becomes `cancelled`. A posted order cannot be cancelled — its charges are on a folio and are reversed there.\n\nEffects: modify hospitality.banquet_event_order.", "operationId": "apply_hospitality_action_cancel_banquet_event_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_event_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.banquet_event_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.cancel_banquet_event_order:apply" ] } ], "summary": "Cancel banquet event order", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.cancel_banquet_event_order/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_cancel_banquet_event_order` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.cancel_banquet_event_order:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_cancel_banquet_event_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_event_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.banquet_event_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Cancel banquet event order (dry-run)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.cancel_banquet_event_order/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_cancel_banquet_event_order`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_cancel_banquet_event_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_event_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Cancel banquet event order (dry-run)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.cancel_banquet_event_order/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_cancel_banquet_event_order` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.cancel_banquet_event_order:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_cancel_banquet_event_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_event_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Cancel banquet event order (rollup delta)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.cancel_channel_reservation/apply": { "post": { "description": "Release a booking the partner cancelled on their side, through the same in-place cancel the desk uses — so the folio, the share group and the inventory all unwind exactly as they would at the front desk. Separate from `apply_channel_reservation` because the required parameters differ: a cancellation names a reservation and nothing else, while a booking needs the whole stay, and one verb whose required set depends on a field it does not carry is a verb no generated SDK or agent tool can call correctly. Releasing recomputes any committed oversell from the new sold count, so the breach unwinds with the booking that caused it. Emits `channel_reservation.applied`.\n\nEffects: modify hospitality.channel_reservation_delivery; modify hospitality.reservation; modify hospitality.availability_day; link hospitality.link.reservation_delivery_produced_reservation; modify hospitality.reservation_room; modify hospitality.share_group; unlink hospitality.link.reservation_in_share_group; modify hospitality.payment_request.", "operationId": "apply_hospitality_action_cancel_channel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancellation_reason": { "title": "Why the partner cancelled", "type": "string" }, "reservation_id": { "format": "uuid", "title": "The reservation the partner cancelled", "type": "string", "x-aerandil-references": "hospitality.reservation" } }, "required": [ "reservation_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_reservation_delivery" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.reservation_delivery_produced_reservation", "hospitality.link.reservation_in_share_group" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.channel_reservation_delivery", "hospitality.reservation", "hospitality.availability_day", "hospitality.reservation_room", "hospitality.share_group", "hospitality.payment_request" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.cancel_channel_reservation:apply" ] } ], "summary": "Cancel channel reservation", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.cancel_channel_reservation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_cancel_channel_reservation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.cancel_channel_reservation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_cancel_channel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancellation_reason": { "title": "Why the partner cancelled", "type": "string" }, "reservation_id": { "format": "uuid", "title": "The reservation the partner cancelled", "type": "string", "x-aerandil-references": "hospitality.reservation" } }, "required": [ "reservation_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_reservation_delivery" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.reservation_delivery_produced_reservation", "hospitality.link.reservation_in_share_group" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.channel_reservation_delivery", "hospitality.reservation", "hospitality.availability_day", "hospitality.reservation_room", "hospitality.share_group", "hospitality.payment_request" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Cancel channel reservation (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.cancel_channel_reservation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_cancel_channel_reservation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_cancel_channel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancellation_reason": { "title": "Why the partner cancelled", "type": "string" }, "reservation_id": { "format": "uuid", "title": "The reservation the partner cancelled", "type": "string", "x-aerandil-references": "hospitality.reservation" } }, "required": [ "reservation_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_reservation_delivery" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Cancel channel reservation (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.cancel_channel_reservation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_cancel_channel_reservation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.cancel_channel_reservation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_cancel_channel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancellation_reason": { "title": "Why the partner cancelled", "type": "string" }, "reservation_id": { "format": "uuid", "title": "The reservation the partner cancelled", "type": "string", "x-aerandil-references": "hospitality.reservation" } }, "required": [ "reservation_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_reservation_delivery" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Cancel channel reservation (rollup delta)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.cancel_federated_run/apply": { "post": { "description": "Operator-initiated cancellation of a federated run before output publication. Transitions run status to `cancelled` and releases the reserved privacy budget — except when the run uses local DP and has already accepted at least one contribution, in which case the local spend is non-recoverable (proposal 0021 §9) and the operator must instead drive `record_federated_aggregation_result` with aggregation_status = `failed` to commit the spend. The 4-clause observation gate (Rogers et al. 2016, Privacy Odometers and Filters, Theorem 3.4; Dwork-Roth, Algorithmic Foundations §3.5 Prop 2.1) is enforced before release: (1) no `commit` event for the run's correlation_id, (2) run status ∈ {queued, privacy_review, approved, collecting, aggregating} (pre-output_review), (3) mechanism_family ≠ `local_dp` OR `participants_accepted` = 0, (4) idempotent on the run's correlation_id (the partial unique index on `privacy_budget_event` enforces single-flight release).\n\nEffects: modify hospitality.federated_run; create hospitality.privacy_budget_event; modify hospitality.privacy_budget_account.", "operationId": "apply_hospitality_action_cancel_federated_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Free-text operator justification (recorded as failure_reason on the run and as the audit-row reason on the release event)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.federated_run", "hospitality.privacy_budget_event", "hospitality.privacy_budget_account" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.cancel_federated_run:apply" ] } ], "summary": "Cancel federated run", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.cancel_federated_run/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_cancel_federated_run` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.cancel_federated_run:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_cancel_federated_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Free-text operator justification (recorded as failure_reason on the run and as the audit-row reason on the release event)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.federated_run", "hospitality.privacy_budget_event", "hospitality.privacy_budget_account" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Cancel federated run (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.cancel_federated_run/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_cancel_federated_run`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_cancel_federated_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Free-text operator justification (recorded as failure_reason on the run and as the audit-row reason on the release event)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Cancel federated run (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.cancel_federated_run/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_cancel_federated_run` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.cancel_federated_run:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_cancel_federated_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Free-text operator justification (recorded as failure_reason on the run and as the audit-row reason on the release event)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Cancel federated run (rollup delta)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.cancel_inspection_round/apply": { "post": { "description": "Abandon an open round, with the `reason`. Its checkpoint results and any faults raised stay. The template's `open_round_id` is cleared and the occurrence is still owed: the template keeps its due date — so the sweep starts a fresh round at once if that date has passed — unless `next_due_on` moves it (the plant room is flooded until Thursday). Cancelling a cancelled round is a no-op; a completed one refuses. Emits `inspection_round.cancelled`.\n\nEffects: modify hospitality.inspection_round; modify hospitality.round_template.", "operationId": "apply_hospitality_action_cancel_inspection_round", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "next_due_on": { "format": "date", "title": "When the template is due again (absent: its due date stands)", "type": "string" }, "reason": { "title": "Why the round was abandoned", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.inspection_round" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.inspection_round", "hospitality.round_template" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.cancel_inspection_round:apply" ] } ], "summary": "Cancel inspection round", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.cancel_inspection_round/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_cancel_inspection_round` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.cancel_inspection_round:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_cancel_inspection_round", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "next_due_on": { "format": "date", "title": "When the template is due again (absent: its due date stands)", "type": "string" }, "reason": { "title": "Why the round was abandoned", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.inspection_round" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.inspection_round", "hospitality.round_template" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Cancel inspection round (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.cancel_inspection_round/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_cancel_inspection_round`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_cancel_inspection_round", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "next_due_on": { "format": "date", "title": "When the template is due again (absent: its due date stands)", "type": "string" }, "reason": { "title": "Why the round was abandoned", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.inspection_round" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Cancel inspection round (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.cancel_inspection_round/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_cancel_inspection_round` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.cancel_inspection_round:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_cancel_inspection_round", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "next_due_on": { "format": "date", "title": "When the template is due again (absent: its due date stands)", "type": "string" }, "reason": { "title": "Why the round was abandoned", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.inspection_round" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Cancel inspection round (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.cancel_membership/apply": { "post": { "description": "Terminate the membership. Structural change only — the refund / settlement consequence is recorded separately via Aerandil's existing charge / payment model. Closes the current `membership_at_tier` link, marks the membership as `terminated`, and pauses billing on the subscription.\n\nEffects: modify hospitality.membership; modify hospitality.membership_subscription; unlink hospitality.link.membership_at_tier.", "operationId": "apply_hospitality_action_cancel_membership", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancelled_at": { "format": "date-time", "title": "When the cancellation took effect", "type": "string" }, "reason": { "title": "Cancellation reason (free text — operator-side analytics)", "type": "string" } }, "required": [ "cancelled_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.membership_at_tier" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.membership", "hospitality.membership_subscription" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.cancel_membership:apply" ] } ], "summary": "Cancel membership", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.cancel_membership/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_cancel_membership` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.cancel_membership:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_cancel_membership", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancelled_at": { "format": "date-time", "title": "When the cancellation took effect", "type": "string" }, "reason": { "title": "Cancellation reason (free text — operator-side analytics)", "type": "string" } }, "required": [ "cancelled_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.membership_at_tier" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.membership", "hospitality.membership_subscription" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Cancel membership (dry-run)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.cancel_membership/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_cancel_membership`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_cancel_membership", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancelled_at": { "format": "date-time", "title": "When the cancellation took effect", "type": "string" }, "reason": { "title": "Cancellation reason (free text — operator-side analytics)", "type": "string" } }, "required": [ "cancelled_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Cancel membership (dry-run)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.cancel_membership/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_cancel_membership` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.cancel_membership:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_cancel_membership", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancelled_at": { "format": "date-time", "title": "When the cancellation took effect", "type": "string" }, "reason": { "title": "Cancellation reason (free text — operator-side analytics)", "type": "string" } }, "required": [ "cancelled_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Cancel membership (rollup delta)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.cancel_payment_request/apply": { "post": { "description": "Withdraw a payment request. Only a `pending` request can be cancelled (Mews: \"Only payment requests which are in Pending state can be canceled\"); the card rail switches its pay link off. Emits `payment_request.cancelled.recorded`.\n\nEffects: modify hospitality.payment_request.", "operationId": "apply_hospitality_action_cancel_payment_request", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancellation_reason": { "title": "Why the house is withdrawing it", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment_request" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.payment_request" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.cancel_payment_request:apply" ] } ], "summary": "Cancel payment request", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.cancel_payment_request/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_cancel_payment_request` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.cancel_payment_request:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_cancel_payment_request", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancellation_reason": { "title": "Why the house is withdrawing it", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment_request" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.payment_request" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Cancel payment request (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.cancel_payment_request/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_cancel_payment_request`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_cancel_payment_request", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancellation_reason": { "title": "Why the house is withdrawing it", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment_request" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Cancel payment request (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.cancel_payment_request/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_cancel_payment_request` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.cancel_payment_request:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_cancel_payment_request", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancellation_reason": { "title": "Why the house is withdrawing it", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment_request" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Cancel payment request (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.cancel_rail_instruction/apply": { "post": { "description": "Take back a card-rail instruction that is still `queued` — a capture, release, refund or departed stay's collection the card rail wrote down while the processor was unreachable — before the rail sends it: the desk is settling it another way, or asked for the wrong thing. Only a `queued` instruction can be cancelled; one the rail is `sending` is being asked of the processor now and finishes on its own, and a final one (done, refused, abandoned, cancelled) stays as it is — cancelling a cancelled one again changes nothing. Nothing is asked of the processor: a queued instruction's earlier attempt that may have reached it is the desk's to check at the dashboard (the instruction's words say so). The payment or stay is free for another card verb at once. Emits `rail_instruction.cancelled`.\n\nEffects: modify hospitality.rail_instruction.", "operationId": "apply_hospitality_action_cancel_rail_instruction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the desk takes it back", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rail_instruction" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.rail_instruction" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.cancel_rail_instruction:apply" ] } ], "summary": "Cancel rail instruction", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.cancel_rail_instruction/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_cancel_rail_instruction` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.cancel_rail_instruction:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_cancel_rail_instruction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the desk takes it back", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rail_instruction" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.rail_instruction" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Cancel rail instruction (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.cancel_rail_instruction/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_cancel_rail_instruction`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_cancel_rail_instruction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the desk takes it back", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rail_instruction" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Cancel rail instruction (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.cancel_rail_instruction/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_cancel_rail_instruction` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.cancel_rail_instruction:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_cancel_rail_instruction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the desk takes it back", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rail_instruction" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Cancel rail instruction (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.cancel_reservation/apply": { "post": { "description": "Move a reservation to cancelled state. Guest-impacting and destructive, so agent principals cannot apply it directly: an agent stages it via `propose_action` and a human confirms (agent_confirm_required).\n\nEffects: modify hospitality.reservation; modify hospitality.availability_day; modify hospitality.reservation_room; modify hospitality.share_group; unlink hospitality.link.reservation_in_share_group; modify hospitality.payment_request.", "operationId": "apply_hospitality_action_cancel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancelled_at": { "format": "date-time", "title": "Cancellation instant (defaults to now; must not precede booked_at)", "type": "string" }, "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.reservation_in_share_group" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.reservation", "hospitality.availability_day", "hospitality.reservation_room", "hospitality.share_group", "hospitality.payment_request" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.cancel_reservation:apply" ] } ], "summary": "Cancel reservation", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.cancel_reservation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_cancel_reservation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.cancel_reservation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_cancel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancelled_at": { "format": "date-time", "title": "Cancellation instant (defaults to now; must not precede booked_at)", "type": "string" }, "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.reservation_in_share_group" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.reservation", "hospitality.availability_day", "hospitality.reservation_room", "hospitality.share_group", "hospitality.payment_request" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Cancel reservation (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.cancel_reservation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_cancel_reservation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_cancel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancelled_at": { "format": "date-time", "title": "Cancellation instant (defaults to now; must not precede booked_at)", "type": "string" }, "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Cancel reservation (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.cancel_reservation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_cancel_reservation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.cancel_reservation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_cancel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancelled_at": { "format": "date-time", "title": "Cancellation instant (defaults to now; must not precede booked_at)", "type": "string" }, "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Cancel reservation (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.cancel_reservation_room/apply": { "post": { "description": "Cancel one room of a multi-room reservation before arrival. The room goes the way a cancelled booking's rooms go (the same leg cascade `cancel_reservation` runs): status cancelled, its room-nights released to the availability ledger (share-aware), its room assignment cleared. The booking stands with the rest: its guest counts re-derive from the live rooms, it reads `modified`, an unpaid deposit re-derives, and the other rooms and every folio are untouched. Penalty, per room: the booking's frozen cancellation terms are split by this room's share of the booking's room revenue — the room records its part of the fee in force at `cancelled_at`, and the booking keeps the rest of every frozen figure — so the policy is never walked again and the two parts always sum to what was frozen. With `outlet_id`, a non-zero part posts to the booking's own account as a cancellation fee. Refuses the last live room (cancel the reservation), a room in house or checked out, and a booking already in house, cancelled or no-show. Replay-iff-identical on `cancelled_at`. Emits `reservation_room.cancelled.decided`. Guest-impacting and destructive, so agents stage it for human confirmation.\n\nEffects: modify hospitality.reservation_room; modify hospitality.reservation; modify hospitality.availability_day; unlink hospitality.link.reservation_room_assigned_to; link hospitality.link.reservation_for_room_type; unlink hospitality.link.reservation_for_room_type; create hospitality.charge; link hospitality.link.charge_at_outlet; create hospitality.tax_application; link hospitality.link.charge_has_tax_application; create hospitality.folio; link hospitality.link.reservation_has_folio; link hospitality.link.folio_has_charge; modify hospitality.folio; modify hospitality.payment_request.", "operationId": "apply_hospitality_action_cancel_reservation_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date the fee posts on (defaults to the property's day of cancelled_at)", "type": "string" }, "cancelled_at": { "format": "date-time", "title": "Cancellation instant (defaults to now; must not precede booked_at)", "type": "string" }, "outlet_id": { "format": "uuid", "title": "Outlet to post the room's fee under (miscellaneous income); absent, nothing is charged", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation_room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated", "linked" ] }, "link_type": { "enum": [ "hospitality.link.reservation_room_assigned_to", "hospitality.link.reservation_for_room_type", "hospitality.link.charge_at_outlet", "hospitality.link.charge_has_tax_application", "hospitality.link.reservation_has_folio", "hospitality.link.folio_has_charge" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.reservation_room", "hospitality.reservation", "hospitality.availability_day", "hospitality.charge", "hospitality.tax_application", "hospitality.folio", "hospitality.payment_request" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.cancel_reservation_room:apply" ] } ], "summary": "Cancel reservation room", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.cancel_reservation_room/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_cancel_reservation_room` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.cancel_reservation_room:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_cancel_reservation_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date the fee posts on (defaults to the property's day of cancelled_at)", "type": "string" }, "cancelled_at": { "format": "date-time", "title": "Cancellation instant (defaults to now; must not precede booked_at)", "type": "string" }, "outlet_id": { "format": "uuid", "title": "Outlet to post the room's fee under (miscellaneous income); absent, nothing is charged", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation_room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated", "linked" ] }, "link_type": { "enum": [ "hospitality.link.reservation_room_assigned_to", "hospitality.link.reservation_for_room_type", "hospitality.link.charge_at_outlet", "hospitality.link.charge_has_tax_application", "hospitality.link.reservation_has_folio", "hospitality.link.folio_has_charge" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.reservation_room", "hospitality.reservation", "hospitality.availability_day", "hospitality.charge", "hospitality.tax_application", "hospitality.folio", "hospitality.payment_request" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Cancel reservation room (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.cancel_reservation_room/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_cancel_reservation_room`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_cancel_reservation_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date the fee posts on (defaults to the property's day of cancelled_at)", "type": "string" }, "cancelled_at": { "format": "date-time", "title": "Cancellation instant (defaults to now; must not precede booked_at)", "type": "string" }, "outlet_id": { "format": "uuid", "title": "Outlet to post the room's fee under (miscellaneous income); absent, nothing is charged", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation_room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Cancel reservation room (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.cancel_reservation_room/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_cancel_reservation_room` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.cancel_reservation_room:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_cancel_reservation_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date the fee posts on (defaults to the property's day of cancelled_at)", "type": "string" }, "cancelled_at": { "format": "date-time", "title": "Cancellation instant (defaults to now; must not precede booked_at)", "type": "string" }, "outlet_id": { "format": "uuid", "title": "Outlet to post the room's fee under (miscellaneous income); absent, nothing is charged", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation_room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Cancel reservation room (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.cancel_room_queue_entry/apply": { "post": { "description": "Withdraw the wait — the guest left for lunch, took another room, or the desk queued in error. Refuses a fulfilled entry (check-in already answered it); re-cancelling is a no-op.\n\nEffects: modify hospitality.room_queue_entry.", "operationId": "apply_hospitality_action_cancel_room_queue_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the wait was withdrawn", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room_queue_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.room_queue_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.cancel_room_queue_entry:apply" ] } ], "summary": "Cancel room queue entry", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.cancel_room_queue_entry/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_cancel_room_queue_entry` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.cancel_room_queue_entry:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_cancel_room_queue_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the wait was withdrawn", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room_queue_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.room_queue_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Cancel room queue entry (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.cancel_room_queue_entry/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_cancel_room_queue_entry`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_cancel_room_queue_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the wait was withdrawn", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room_queue_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Cancel room queue entry (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.cancel_room_queue_entry/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_cancel_room_queue_entry` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.cancel_room_queue_entry:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_cancel_room_queue_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the wait was withdrawn", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room_queue_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Cancel room queue entry (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.cancel_waitlist_entry/apply": { "post": { "description": "Withdraw the wait — the guest booked elsewhere, or the desk is clearing a stale list. Re-cancelling is a no-op. Refuses an accepted entry (the reservation it became is the thing to cancel, through `cancel_reservation`) and an expired one (the night audit already closed it).\n\nEffects: modify hospitality.waitlist_entry; modify hospitality.availability_day.", "operationId": "apply_hospitality_action_cancel_waitlist_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the wait was withdrawn", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.waitlist_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.waitlist_entry", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.cancel_waitlist_entry:apply" ] } ], "summary": "Cancel waitlist entry", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.cancel_waitlist_entry/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_cancel_waitlist_entry` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.cancel_waitlist_entry:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_cancel_waitlist_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the wait was withdrawn", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.waitlist_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.waitlist_entry", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Cancel waitlist entry (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.cancel_waitlist_entry/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_cancel_waitlist_entry`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_cancel_waitlist_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the wait was withdrawn", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.waitlist_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Cancel waitlist entry (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.cancel_waitlist_entry/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_cancel_waitlist_entry` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.cancel_waitlist_entry:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_cancel_waitlist_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the wait was withdrawn", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.waitlist_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Cancel waitlist entry (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.cancel_workflow_run/apply": { "post": { "description": "Request cancellation and optional compensation of a running workflow. Transitions the run to `cancel_requested`; cancels ready / waiting steps; enters `compensating` when `compensate_completed_steps = true` and any successful terminal steps are compensatable, otherwise transitions directly to `canceled`. Advancing from `compensating` to `compensated` / `compensation_failed` requires the future runner or a trusted host to call the declared compensations and then `record_compensation_result`. The cancellation event uses the calling principal; per-compensation events carry their proximate executor with `delegated_from_principal` pointing back to the canceller.\n\nEffects: modify hospitality.workflow_run; modify hospitality.workflow_step_run.", "operationId": "apply_hospitality_action_cancel_workflow_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancel_reason": { "title": "Required text reason", "type": "string" }, "canceled_at": { "format": "date-time", "title": "Defaults to now()", "type": "string" }, "compensate_completed_steps": { "title": "Whether to enter compensation", "type": "boolean" } }, "required": [ "cancel_reason", "compensate_completed_steps" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.workflow_run", "hospitality.workflow_step_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.cancel_workflow_run:apply" ] } ], "summary": "Cancel workflow run", "tags": [ "workflows" ] } }, "/v1/actions/hospitality.action.cancel_workflow_run/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_cancel_workflow_run` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.cancel_workflow_run:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_cancel_workflow_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancel_reason": { "title": "Required text reason", "type": "string" }, "canceled_at": { "format": "date-time", "title": "Defaults to now()", "type": "string" }, "compensate_completed_steps": { "title": "Whether to enter compensation", "type": "boolean" } }, "required": [ "cancel_reason", "compensate_completed_steps" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.workflow_run", "hospitality.workflow_step_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Cancel workflow run (dry-run)", "tags": [ "workflows" ] } }, "/v1/actions/hospitality.action.cancel_workflow_run/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_cancel_workflow_run`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_cancel_workflow_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancel_reason": { "title": "Required text reason", "type": "string" }, "canceled_at": { "format": "date-time", "title": "Defaults to now()", "type": "string" }, "compensate_completed_steps": { "title": "Whether to enter compensation", "type": "boolean" } }, "required": [ "cancel_reason", "compensate_completed_steps" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Cancel workflow run (dry-run)", "tags": [ "workflows" ] } }, "/v1/actions/hospitality.action.cancel_workflow_run/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_cancel_workflow_run` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.cancel_workflow_run:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_cancel_workflow_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancel_reason": { "title": "Required text reason", "type": "string" }, "canceled_at": { "format": "date-time", "title": "Defaults to now()", "type": "string" }, "compensate_completed_steps": { "title": "Whether to enter compensation", "type": "boolean" } }, "required": [ "cancel_reason", "compensate_completed_steps" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Cancel workflow run (rollup delta)", "tags": [ "workflows" ] } }, "/v1/actions/hospitality.action.capture_authorised_charge/apply": { "post": { "description": "Record the terminal capture transition on a previously-authorised Payment. Validators reject: status != pending, review_state in {declined, expired}, payment_method_token shaped like a PAN, folio closed/void. Atomically transitions status = pending -> settled and review_state = held -> approved (when previously held). Captures the full authorised amount unless `captured_amount` names a smaller one — the guest who spent less than the hold — in which case the payment's amount becomes what was taken. Multi-capture stays deferred per proposal 0018 §1.\n\nEffects: modify hospitality.payment; modify hospitality.folio.", "operationId": "apply_hospitality_action_capture_authorised_charge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "acquirer_reference_number": { "title": "23-digit ARN if available (often null at capture time; lands hours later via PSP reconciliation)", "type": "string" }, "captured_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Captured amount", "type": "object" }, "captured_at": { "format": "date-time", "title": "PSP-side capture confirmation timestamp (defaults to now)", "type": "string" }, "card_present": { "title": "Whether the fee was priced as card-present", "type": "boolean" }, "fee_class": { "enum": [ "domestic_standard", "domestic_premium", "regional", "international" ], "title": "The card's class the fee was priced by", "type": "string" }, "platform_fee": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Platform fee", "type": "object" }, "processor_fee_estimate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Fee estimate", "type": "object" }, "psp_capture_reference": { "title": "PSP-issued capture reference (Stripe charge.id / Adyen capture pspReference / Checkout.com action_id / Cybersource capture id)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.payment", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.capture_authorised_charge:apply" ] } ], "summary": "Capture authorised charge", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.capture_authorised_charge/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_capture_authorised_charge` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.capture_authorised_charge:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_capture_authorised_charge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "acquirer_reference_number": { "title": "23-digit ARN if available (often null at capture time; lands hours later via PSP reconciliation)", "type": "string" }, "captured_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Captured amount", "type": "object" }, "captured_at": { "format": "date-time", "title": "PSP-side capture confirmation timestamp (defaults to now)", "type": "string" }, "card_present": { "title": "Whether the fee was priced as card-present", "type": "boolean" }, "fee_class": { "enum": [ "domestic_standard", "domestic_premium", "regional", "international" ], "title": "The card's class the fee was priced by", "type": "string" }, "platform_fee": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Platform fee", "type": "object" }, "processor_fee_estimate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Fee estimate", "type": "object" }, "psp_capture_reference": { "title": "PSP-issued capture reference (Stripe charge.id / Adyen capture pspReference / Checkout.com action_id / Cybersource capture id)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.payment", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Capture authorised charge (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.capture_authorised_charge/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_capture_authorised_charge`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_capture_authorised_charge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "acquirer_reference_number": { "title": "23-digit ARN if available (often null at capture time; lands hours later via PSP reconciliation)", "type": "string" }, "captured_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Captured amount", "type": "object" }, "captured_at": { "format": "date-time", "title": "PSP-side capture confirmation timestamp (defaults to now)", "type": "string" }, "card_present": { "title": "Whether the fee was priced as card-present", "type": "boolean" }, "fee_class": { "enum": [ "domestic_standard", "domestic_premium", "regional", "international" ], "title": "The card's class the fee was priced by", "type": "string" }, "platform_fee": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Platform fee", "type": "object" }, "processor_fee_estimate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Fee estimate", "type": "object" }, "psp_capture_reference": { "title": "PSP-issued capture reference (Stripe charge.id / Adyen capture pspReference / Checkout.com action_id / Cybersource capture id)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Capture authorised charge (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.capture_authorised_charge/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_capture_authorised_charge` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.capture_authorised_charge:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_capture_authorised_charge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "acquirer_reference_number": { "title": "23-digit ARN if available (often null at capture time; lands hours later via PSP reconciliation)", "type": "string" }, "captured_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Captured amount", "type": "object" }, "captured_at": { "format": "date-time", "title": "PSP-side capture confirmation timestamp (defaults to now)", "type": "string" }, "card_present": { "title": "Whether the fee was priced as card-present", "type": "boolean" }, "fee_class": { "enum": [ "domestic_standard", "domestic_premium", "regional", "international" ], "title": "The card's class the fee was priced by", "type": "string" }, "platform_fee": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Platform fee", "type": "object" }, "processor_fee_estimate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Fee estimate", "type": "object" }, "psp_capture_reference": { "title": "PSP-issued capture reference (Stripe charge.id / Adyen capture pspReference / Checkout.com action_id / Cybersource capture id)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Capture authorised charge (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.capture_guest_id/apply": { "post": { "description": "Record a minimal government-ID document for a guest (statutory registration). Stores only typed facts + a verification result; the raw number / scan is never stored — pass `external_record_reference_id` pointing at an `identity`-domain external record for the vault-held artifact. `retain_until` is the storage-limitation clock.\n\nEffects: create hospitality.guest_id_document; link hospitality.link.guest_id_document_for_person; link hospitality.link.guest_id_document_references_external_record.", "operationId": "apply_hospitality_action_capture_guest_id", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "document_number_last4": { "title": "Last 4 glyphs of the document number (never the full number)", "type": "string" }, "document_type": { "enum": [ "passport", "visa", "national_id", "drivers_licence", "residence_permit" ], "title": "Document type", "type": "string" }, "expiry_date": { "format": "date", "title": "Document expiry date", "type": "string" }, "external_record_reference_id": { "format": "uuid", "title": "Optional pointer to the identity-domain external vault record", "type": "string", "x-aerandil-references": "hospitality.external_record_reference" }, "holder_name": { "title": "Holder name as printed", "type": "string" }, "issuing_country": { "title": "Issuing country (ISO 3166-1 alpha-2)", "type": "string" }, "retain_until": { "format": "date", "title": "Retain-until date (storage-limitation clock; set per jurisdiction)", "type": "string" }, "verification_method": { "enum": [ "manual_visual", "document_scan", "nfc_chip", "third_party_idv", "government_registry" ], "title": "Verification method", "type": "string" }, "verification_status": { "enum": [ "unverified", "verified", "failed", "expired" ], "title": "Verification status (default unverified)", "type": "string" } }, "required": [ "document_type", "issuing_country", "retain_until" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.guest_id_document_for_person", "hospitality.link.guest_id_document_references_external_record" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.guest_id_document" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.capture_guest_id:apply" ] } ], "summary": "Capture guest ID", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.capture_guest_id/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_capture_guest_id` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.capture_guest_id:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_capture_guest_id", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "document_number_last4": { "title": "Last 4 glyphs of the document number (never the full number)", "type": "string" }, "document_type": { "enum": [ "passport", "visa", "national_id", "drivers_licence", "residence_permit" ], "title": "Document type", "type": "string" }, "expiry_date": { "format": "date", "title": "Document expiry date", "type": "string" }, "external_record_reference_id": { "format": "uuid", "title": "Optional pointer to the identity-domain external vault record", "type": "string", "x-aerandil-references": "hospitality.external_record_reference" }, "holder_name": { "title": "Holder name as printed", "type": "string" }, "issuing_country": { "title": "Issuing country (ISO 3166-1 alpha-2)", "type": "string" }, "retain_until": { "format": "date", "title": "Retain-until date (storage-limitation clock; set per jurisdiction)", "type": "string" }, "verification_method": { "enum": [ "manual_visual", "document_scan", "nfc_chip", "third_party_idv", "government_registry" ], "title": "Verification method", "type": "string" }, "verification_status": { "enum": [ "unverified", "verified", "failed", "expired" ], "title": "Verification status (default unverified)", "type": "string" } }, "required": [ "document_type", "issuing_country", "retain_until" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.guest_id_document_for_person", "hospitality.link.guest_id_document_references_external_record" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.guest_id_document" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Capture guest ID (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.capture_guest_id/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_capture_guest_id`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_capture_guest_id", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "document_number_last4": { "title": "Last 4 glyphs of the document number (never the full number)", "type": "string" }, "document_type": { "enum": [ "passport", "visa", "national_id", "drivers_licence", "residence_permit" ], "title": "Document type", "type": "string" }, "expiry_date": { "format": "date", "title": "Document expiry date", "type": "string" }, "external_record_reference_id": { "format": "uuid", "title": "Optional pointer to the identity-domain external vault record", "type": "string", "x-aerandil-references": "hospitality.external_record_reference" }, "holder_name": { "title": "Holder name as printed", "type": "string" }, "issuing_country": { "title": "Issuing country (ISO 3166-1 alpha-2)", "type": "string" }, "retain_until": { "format": "date", "title": "Retain-until date (storage-limitation clock; set per jurisdiction)", "type": "string" }, "verification_method": { "enum": [ "manual_visual", "document_scan", "nfc_chip", "third_party_idv", "government_registry" ], "title": "Verification method", "type": "string" }, "verification_status": { "enum": [ "unverified", "verified", "failed", "expired" ], "title": "Verification status (default unverified)", "type": "string" } }, "required": [ "document_type", "issuing_country", "retain_until" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Capture guest ID (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.capture_guest_id/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_capture_guest_id` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.capture_guest_id:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_capture_guest_id", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "document_number_last4": { "title": "Last 4 glyphs of the document number (never the full number)", "type": "string" }, "document_type": { "enum": [ "passport", "visa", "national_id", "drivers_licence", "residence_permit" ], "title": "Document type", "type": "string" }, "expiry_date": { "format": "date", "title": "Document expiry date", "type": "string" }, "external_record_reference_id": { "format": "uuid", "title": "Optional pointer to the identity-domain external vault record", "type": "string", "x-aerandil-references": "hospitality.external_record_reference" }, "holder_name": { "title": "Holder name as printed", "type": "string" }, "issuing_country": { "title": "Issuing country (ISO 3166-1 alpha-2)", "type": "string" }, "retain_until": { "format": "date", "title": "Retain-until date (storage-limitation clock; set per jurisdiction)", "type": "string" }, "verification_method": { "enum": [ "manual_visual", "document_scan", "nfc_chip", "third_party_idv", "government_registry" ], "title": "Verification method", "type": "string" }, "verification_status": { "enum": [ "unverified", "verified", "failed", "expired" ], "title": "Verification status (default unverified)", "type": "string" } }, "required": [ "document_type", "issuing_country", "retain_until" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Capture guest ID (rollup delta)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.certify_metric/apply": { "post": { "description": "Record operator sign-off on a `draft` definition: status → `certified`, `certified_at` / `certified_by` stamped from the acting principal. Idempotent on an already-certified version; a deprecated version cannot be re-certified (revise to a new version instead). Certifying an organisation-wide metric may route through a 0020 approval gate by operator policy; the action itself is gate-agnostic. Emits `metric.certified`.\n\nEffects: modify hospitality.metric_definition.", "operationId": "apply_hospitality_action_certify_metric", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.metric_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.metric_definition" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.certify_metric:apply" ] } ], "summary": "Certify metric", "tags": [ "catalogue" ] } }, "/v1/actions/hospitality.action.certify_metric/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_certify_metric` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.certify_metric:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_certify_metric", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.metric_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.metric_definition" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Certify metric (dry-run)", "tags": [ "catalogue" ] } }, "/v1/actions/hospitality.action.certify_metric/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_certify_metric`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_certify_metric", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.metric_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Certify metric (dry-run)", "tags": [ "catalogue" ] } }, "/v1/actions/hospitality.action.certify_metric/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_certify_metric` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.certify_metric:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_certify_metric", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.metric_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Certify metric (rollup delta)", "tags": [ "catalogue" ] } }, "/v1/actions/hospitality.action.change_block_status/apply": { "post": { "description": "Move a block between `tentative`, `definite` and `cancelled`. Becoming `definite` materialises the hold — every allocated night is taken out of house availability, and a night that cannot cover the allotment refuses the whole transition. Leaving `definite` returns every unpicked room. Going back to `tentative` is refused once anything has been picked up, since live reservations would lose the hold beneath them.\n\nEffects: modify hospitality.group_block; modify hospitality.block_allocation; modify hospitality.availability_day.", "operationId": "apply_hospitality_action_change_block_status", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the status changed", "type": "string" }, "status": { "enum": [ "tentative", "definite", "cancelled" ], "title": "New status", "type": "string" } }, "required": [ "status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_block" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.group_block", "hospitality.block_allocation", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.change_block_status:apply" ] } ], "summary": "Change block status", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.change_block_status/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_change_block_status` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.change_block_status:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_change_block_status", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the status changed", "type": "string" }, "status": { "enum": [ "tentative", "definite", "cancelled" ], "title": "New status", "type": "string" } }, "required": [ "status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_block" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.group_block", "hospitality.block_allocation", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Change block status (dry-run)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.change_block_status/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_change_block_status`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_change_block_status", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the status changed", "type": "string" }, "status": { "enum": [ "tentative", "definite", "cancelled" ], "title": "New status", "type": "string" } }, "required": [ "status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_block" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Change block status (dry-run)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.change_block_status/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_change_block_status` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.change_block_status:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_change_block_status", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the status changed", "type": "string" }, "status": { "enum": [ "tentative", "definite", "cancelled" ], "title": "New status", "type": "string" } }, "required": [ "status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_block" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Change block status (rollup delta)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.change_function_event_status/apply": { "post": { "description": "Move an event between `tentative`, `definite` and `cancelled`. `actual` is not a move — `record_function_event_actuals` sets it with the count. Cancelling an event cancels its unposted banquet event order with it; a posted order cannot be cancelled, so neither can its event.\n\nEffects: modify hospitality.function_event; modify hospitality.banquet_event_order.", "operationId": "apply_hospitality_action_change_function_event_status", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "status": { "enum": [ "tentative", "definite", "cancelled" ], "title": "Target status", "type": "string" } }, "required": [ "status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_event" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.function_event", "hospitality.banquet_event_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.change_function_event_status:apply" ] } ], "summary": "Change function event status", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.change_function_event_status/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_change_function_event_status` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.change_function_event_status:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_change_function_event_status", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "status": { "enum": [ "tentative", "definite", "cancelled" ], "title": "Target status", "type": "string" } }, "required": [ "status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_event" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.function_event", "hospitality.banquet_event_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Change function event status (dry-run)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.change_function_event_status/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_change_function_event_status`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_change_function_event_status", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "status": { "enum": [ "tentative", "definite", "cancelled" ], "title": "Target status", "type": "string" } }, "required": [ "status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_event" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Change function event status (dry-run)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.change_function_event_status/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_change_function_event_status` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.change_function_event_status:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_change_function_event_status", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "status": { "enum": [ "tentative", "definite", "cancelled" ], "title": "Target status", "type": "string" } }, "required": [ "status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_event" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Change function event status (rollup delta)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.change_reservation_occupancy/apply": { "post": { "description": "Change one reservation_room's guest counts — allowed pre-arrival and in-house (an extra guest joining mid-stay is normal operations). The new adults + children must fit the leg's room type max_occupancy. The leg's nights re-price per the required pricing_policy (keep_rate leaves them; requote reads the grid at the new adult count — occupancy-based pricing as a first-class re-price, the Mews gap; override takes the supplied rate with its reason; requote_added_nights_only has no meaning here and is refused). Reservation-level totals re-derive as the sum across legs.\n\nEffects: modify hospitality.reservation_room; modify hospitality.reservation; modify hospitality.reservation_night; modify hospitality.payment_request.\n\nStep-up when `pricing_policy` is `override`: a person (a `User` principal) needs a fresh desk step-up proof — Pricing nights at a typed-in rate overrides the house's published price — or the call is refused `403 step_up_required` before anything runs. Re-enter the passcode at `POST /v1/desk/sessions/{id}/passcode` and retry. Machine principals are not gated.", "operationId": "apply_hospitality_action_change_reservation_occupancy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults": { "title": "Adults", "type": "integer" }, "children": { "title": "Children", "type": "integer" }, "override_nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate for pricing_policy = override", "type": "object" }, "override_reason": { "title": "Why the override price (required with pricing_policy = override)", "type": "string" }, "pricing_policy": { "enum": [ "keep_rate", "requote", "requote_added_nights_only", "override" ], "title": "How affected nights re-price (required; never silent)", "type": "string" } }, "required": [ "adults", "children", "pricing_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation_room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.reservation_room", "hospitality.reservation", "hospitality.reservation_night", "hospitality.payment_request" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "403": { "description": "`step_up_required` — a person applied this without a fresh desk step-up proof; nothing ran." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.change_reservation_occupancy:apply" ] } ], "summary": "Change reservation occupancy", "tags": [ "booking" ], "x-aerandil-step-up": { "reason": "Pricing nights at a typed-in rate overrides the house's published price", "when": { "kind": "param_equals", "param": "pricing_policy", "value": "override" } } } }, "/v1/actions/hospitality.action.change_reservation_occupancy/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_change_reservation_occupancy` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.change_reservation_occupancy:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_change_reservation_occupancy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults": { "title": "Adults", "type": "integer" }, "children": { "title": "Children", "type": "integer" }, "override_nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate for pricing_policy = override", "type": "object" }, "override_reason": { "title": "Why the override price (required with pricing_policy = override)", "type": "string" }, "pricing_policy": { "enum": [ "keep_rate", "requote", "requote_added_nights_only", "override" ], "title": "How affected nights re-price (required; never silent)", "type": "string" } }, "required": [ "adults", "children", "pricing_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation_room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.reservation_room", "hospitality.reservation", "hospitality.reservation_night", "hospitality.payment_request" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Change reservation occupancy (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.change_reservation_occupancy/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_change_reservation_occupancy`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_change_reservation_occupancy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults": { "title": "Adults", "type": "integer" }, "children": { "title": "Children", "type": "integer" }, "override_nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate for pricing_policy = override", "type": "object" }, "override_reason": { "title": "Why the override price (required with pricing_policy = override)", "type": "string" }, "pricing_policy": { "enum": [ "keep_rate", "requote", "requote_added_nights_only", "override" ], "title": "How affected nights re-price (required; never silent)", "type": "string" } }, "required": [ "adults", "children", "pricing_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation_room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Change reservation occupancy (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.change_reservation_occupancy/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_change_reservation_occupancy` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.change_reservation_occupancy:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_change_reservation_occupancy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults": { "title": "Adults", "type": "integer" }, "children": { "title": "Children", "type": "integer" }, "override_nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate for pricing_policy = override", "type": "object" }, "override_reason": { "title": "Why the override price (required with pricing_policy = override)", "type": "string" }, "pricing_policy": { "enum": [ "keep_rate", "requote", "requote_added_nights_only", "override" ], "title": "How affected nights re-price (required; never silent)", "type": "string" } }, "required": [ "adults", "children", "pricing_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation_room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Change reservation occupancy (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.change_reservation_room_type/apply": { "post": { "description": "Re-book one reservation_room onto a different room type — per-leg, so a two-room booking upgrades one room without touching the other. Pre-check-in only. Releases the old type's room-nights, consumes the new type's (sold-out nights refuse atomically), re-runs the restriction gate for the new type, re-points reservation_room_for_room_type, and re-prices the leg's nights per the required pricing_policy (requote_added_nights_only has no meaning here and is refused). An assigned physical room of the wrong type is explicitly unassigned — a guest is never left silently booked into a mismatched room — and the reservation-level room-type convenience link re-derives from the legs.\n\nEffects: modify hospitality.reservation_room; modify hospitality.reservation; modify hospitality.availability_day; modify hospitality.reservation_night; link hospitality.link.reservation_room_for_room_type; unlink hospitality.link.reservation_room_for_room_type; link hospitality.link.reservation_for_room_type; unlink hospitality.link.reservation_for_room_type; unlink hospitality.link.reservation_room_assigned_to; modify hospitality.payment_request.\n\nStep-up when `pricing_policy` is `override`: a person (a `User` principal) needs a fresh desk step-up proof — Pricing nights at a typed-in rate overrides the house's published price — or the call is refused `403 step_up_required` before anything runs. Re-enter the passcode at `POST /v1/desk/sessions/{id}/passcode` and retry. Machine principals are not gated.", "operationId": "apply_hospitality_action_change_reservation_room_type", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "new_room_type_id": { "format": "uuid", "title": "New room type", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "override_nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate for pricing_policy = override", "type": "object" }, "override_reason": { "title": "Why the override price (required with pricing_policy = override)", "type": "string" }, "pricing_policy": { "enum": [ "keep_rate", "requote", "requote_added_nights_only", "override" ], "title": "How affected nights re-price (required; never silent)", "type": "string" } }, "required": [ "new_room_type_id", "pricing_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation_room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.reservation_room_for_room_type", "hospitality.link.reservation_for_room_type", "hospitality.link.reservation_room_assigned_to" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.reservation_room", "hospitality.reservation", "hospitality.availability_day", "hospitality.reservation_night", "hospitality.payment_request" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "403": { "description": "`step_up_required` — a person applied this without a fresh desk step-up proof; nothing ran." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.change_reservation_room_type:apply" ] } ], "summary": "Change reservation room type", "tags": [ "booking" ], "x-aerandil-step-up": { "reason": "Pricing nights at a typed-in rate overrides the house's published price", "when": { "kind": "param_equals", "param": "pricing_policy", "value": "override" } } } }, "/v1/actions/hospitality.action.change_reservation_room_type/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_change_reservation_room_type` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.change_reservation_room_type:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_change_reservation_room_type", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "new_room_type_id": { "format": "uuid", "title": "New room type", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "override_nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate for pricing_policy = override", "type": "object" }, "override_reason": { "title": "Why the override price (required with pricing_policy = override)", "type": "string" }, "pricing_policy": { "enum": [ "keep_rate", "requote", "requote_added_nights_only", "override" ], "title": "How affected nights re-price (required; never silent)", "type": "string" } }, "required": [ "new_room_type_id", "pricing_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation_room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.reservation_room_for_room_type", "hospitality.link.reservation_for_room_type", "hospitality.link.reservation_room_assigned_to" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.reservation_room", "hospitality.reservation", "hospitality.availability_day", "hospitality.reservation_night", "hospitality.payment_request" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Change reservation room type (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.change_reservation_room_type/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_change_reservation_room_type`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_change_reservation_room_type", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "new_room_type_id": { "format": "uuid", "title": "New room type", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "override_nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate for pricing_policy = override", "type": "object" }, "override_reason": { "title": "Why the override price (required with pricing_policy = override)", "type": "string" }, "pricing_policy": { "enum": [ "keep_rate", "requote", "requote_added_nights_only", "override" ], "title": "How affected nights re-price (required; never silent)", "type": "string" } }, "required": [ "new_room_type_id", "pricing_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation_room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Change reservation room type (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.change_reservation_room_type/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_change_reservation_room_type` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.change_reservation_room_type:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_change_reservation_room_type", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "new_room_type_id": { "format": "uuid", "title": "New room type", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "override_nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate for pricing_policy = override", "type": "object" }, "override_reason": { "title": "Why the override price (required with pricing_policy = override)", "type": "string" }, "pricing_policy": { "enum": [ "keep_rate", "requote", "requote_added_nights_only", "override" ], "title": "How affected nights re-price (required; never silent)", "type": "string" } }, "required": [ "new_room_type_id", "pricing_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation_room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Change reservation room type (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.change_tier/apply": { "post": { "description": "Transition the target membership to a new tier. Supersedes the existing `membership_at_tier` link (sets `effective_to`) and creates a new link with `effective_from`. Dues adjustment is handled via the optional subscription amount parameter; the refund / proration consequence depends on the tier's `prorates_on_change` flag.\n\nEffects: link hospitality.link.membership_at_tier; modify hospitality.membership_subscription; unlink hospitality.link.membership_at_tier.", "operationId": "apply_hospitality_action_change_tier", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date-time", "title": "Tier change effective date", "type": "string" }, "new_subscription_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Updated subscription amount (when tier change implies dues change)", "type": "object" }, "new_tier_id": { "format": "uuid", "title": "Target tier", "type": "string", "x-aerandil-references": "hospitality.membership_tier" } }, "required": [ "new_tier_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.membership_at_tier" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.membership_subscription" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.change_tier:apply" ] } ], "summary": "Change tier", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.change_tier/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_change_tier` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.change_tier:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_change_tier", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date-time", "title": "Tier change effective date", "type": "string" }, "new_subscription_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Updated subscription amount (when tier change implies dues change)", "type": "object" }, "new_tier_id": { "format": "uuid", "title": "Target tier", "type": "string", "x-aerandil-references": "hospitality.membership_tier" } }, "required": [ "new_tier_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.membership_at_tier" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.membership_subscription" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Change tier (dry-run)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.change_tier/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_change_tier`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_change_tier", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date-time", "title": "Tier change effective date", "type": "string" }, "new_subscription_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Updated subscription amount (when tier change implies dues change)", "type": "object" }, "new_tier_id": { "format": "uuid", "title": "Target tier", "type": "string", "x-aerandil-references": "hospitality.membership_tier" } }, "required": [ "new_tier_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Change tier (dry-run)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.change_tier/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_change_tier` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.change_tier:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_change_tier", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date-time", "title": "Tier change effective date", "type": "string" }, "new_subscription_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Updated subscription amount (when tier change implies dues change)", "type": "object" }, "new_tier_id": { "format": "uuid", "title": "Target tier", "type": "string", "x-aerandil-references": "hospitality.membership_tier" } }, "required": [ "new_tier_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Change tier (rollup delta)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.charge_virtual_card/apply": { "post": { "description": "Ask the card rail to charge an OTA virtual card for what its booking owes — the channel's card, charged once the channel's activation date has come at the house (`activation_at`). The standing automation `virtual_card_charge_on_activation` applies it; the desk may too, and may ask again after a refusal. The amount is what the booking owes (`expected_total` less `deposit_paid_amount`), never more than the card was funded with (`funded_amount`), and the funded amount alone when the booking froze no total. Refused for anything but an active `virtual` card, or before its activation instant. A card already `requested` or `charged` changes nothing, so a sweep that fires twice asks once. When there is nothing to charge — the booking was cancelled, nothing says what it owes, or it owes nothing — the card records `refused` with the reason instead. Emits `payment_card.activation_charge_requested.recorded` (the card rail charges it off-session) or `payment_card.activation_charge_refused.recorded`.\n\nEffects: modify hospitality.payment_card.", "operationId": "apply_hospitality_action_charge_virtual_card", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment_card" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.payment_card" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.charge_virtual_card:apply" ] } ], "summary": "Charge virtual card", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.charge_virtual_card/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_charge_virtual_card` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.charge_virtual_card:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_charge_virtual_card", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment_card" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.payment_card" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Charge virtual card (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.charge_virtual_card/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_charge_virtual_card`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_charge_virtual_card", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment_card" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Charge virtual card (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.charge_virtual_card/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_charge_virtual_card` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.charge_virtual_card:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_charge_virtual_card", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment_card" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Charge virtual card (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.check_in/apply": { "post": { "description": "Mark arriving guests as in-house: one stay and one window-1 folio per reservation_room (the multi-room stay model — the folio's opened_at is the actual arrival, business time, not record time). The whole party checks in by default; pass reservation_room_ids for a staggered arrival's subset. Replay-iff-identical per leg: re-applying with the arrival_actual a leg's stay already carries skips that leg, so connector variant steps and crashed-pass retries are safe. A day-use arrival also posts the slot's one room charge (with derived tax lines) to the leg's new folio — the night audit never sees a zero-night stay, so check-in is its posting moment; a zero slot rate is a comp and posts nothing.\n\nEffects: modify hospitality.reservation; modify hospitality.reservation_room; create hospitality.stay; create hospitality.folio; link hospitality.link.reservation_has_stay; link hospitality.link.stay_for_reservation_room; link hospitality.link.stay_in_room; link hospitality.link.stay_has_folio; modify hospitality.room; modify hospitality.room_discrepancy; modify hospitality.room_queue_entry; create hospitality.charge; create hospitality.tax_application; link hospitality.link.folio_has_charge; link hospitality.link.charge_at_outlet; link hospitality.link.charge_has_tax_application; modify hospitality.folio; modify hospitality.payment_request.", "operationId": "apply_hospitality_action_check_in", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "arrival_actual": { "format": "date-time", "title": "Actual arrival", "type": "string" }, "reservation_room_ids": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation_room" }, "title": "Legs to check in (default: every leg — the whole party)", "type": "array" } }, "required": [ "arrival_actual" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.reservation_has_stay", "hospitality.link.stay_for_reservation_room", "hospitality.link.stay_in_room", "hospitality.link.stay_has_folio", "hospitality.link.folio_has_charge", "hospitality.link.charge_at_outlet", "hospitality.link.charge_has_tax_application" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.reservation", "hospitality.reservation_room", "hospitality.stay", "hospitality.folio", "hospitality.room", "hospitality.room_discrepancy", "hospitality.room_queue_entry", "hospitality.charge", "hospitality.tax_application", "hospitality.payment_request" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.check_in:apply" ] } ], "summary": "Check in", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.check_in/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_check_in` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.check_in:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_check_in", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "arrival_actual": { "format": "date-time", "title": "Actual arrival", "type": "string" }, "reservation_room_ids": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation_room" }, "title": "Legs to check in (default: every leg — the whole party)", "type": "array" } }, "required": [ "arrival_actual" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.reservation_has_stay", "hospitality.link.stay_for_reservation_room", "hospitality.link.stay_in_room", "hospitality.link.stay_has_folio", "hospitality.link.folio_has_charge", "hospitality.link.charge_at_outlet", "hospitality.link.charge_has_tax_application" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.reservation", "hospitality.reservation_room", "hospitality.stay", "hospitality.folio", "hospitality.room", "hospitality.room_discrepancy", "hospitality.room_queue_entry", "hospitality.charge", "hospitality.tax_application", "hospitality.payment_request" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Check in (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.check_in/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_check_in`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_check_in", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "arrival_actual": { "format": "date-time", "title": "Actual arrival", "type": "string" }, "reservation_room_ids": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation_room" }, "title": "Legs to check in (default: every leg — the whole party)", "type": "array" } }, "required": [ "arrival_actual" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Check in (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.check_in/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_check_in` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.check_in:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_check_in", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "arrival_actual": { "format": "date-time", "title": "Actual arrival", "type": "string" }, "reservation_room_ids": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation_room" }, "title": "Legs to check in (default: every leg — the whole party)", "type": "array" } }, "required": [ "arrival_actual" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Check in (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.check_in_appointment/apply": { "post": { "description": "The guest arrived at the spa desk: booked / confirmed → checked_in (Book4Time front-desk check-in; Mangomint's waiting room). Business time: `checked_in_at` defaults to now. Re-checking-in is a no-op. Emits `spa.appointment_checked_in`.\n\nEffects: modify hospitality.appointment.", "operationId": "apply_hospitality_action_check_in_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "checked_in_at": { "format": "date-time", "title": "When the guest arrived (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.appointment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.check_in_appointment:apply" ] } ], "summary": "Check in appointment", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.check_in_appointment/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_check_in_appointment` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.check_in_appointment:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_check_in_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "checked_in_at": { "format": "date-time", "title": "When the guest arrived (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.appointment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Check in appointment (dry-run)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.check_in_appointment/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_check_in_appointment`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_check_in_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "checked_in_at": { "format": "date-time", "title": "When the guest arrived (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Check in appointment (dry-run)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.check_in_appointment/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_check_in_appointment` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.check_in_appointment:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_check_in_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "checked_in_at": { "format": "date-time", "title": "When the guest arrived (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Check in appointment (rollup delta)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.check_out/apply": { "post": { "description": "Mark departing guests as checked out and close each departing stay's open folio windows (closed_at is the actual departure — business time). The whole party departs by default; pass reservation_room_ids for a staggered departure's subset — the reservation completes only when no leg remains in house, and never-arrived legs cancel at that moment with their unslept nights released back to inventory. Refuses a non-zero folio balance unless `allow_open_balance` is set: front-desk flows settle first, while a connector mirroring a vendor's already-departed guest records the fact and lets the charges / payments streams settle the folio in their own passes. Replay-iff-identical per leg: re-applying with the departure_actual a leg's stay already carries skips that leg. Every pending card hold the departure leaves is decided (`payment.hold_decision`, `payment.hold_decided`): released, taken for what a bill still owes, or — with the house's post-stay window on (`set_post_stay_charging`) — the stay's largest kept until the window's end, the stay stamped `post_stay_window = open`. The card rail carries the decision out at the processor after commit.\n\nEffects: modify hospitality.reservation; modify hospitality.availability_day; modify hospitality.reservation_room; modify hospitality.stay; modify hospitality.folio; modify hospitality.access_credential; modify hospitality.room; modify hospitality.room_discrepancy; modify hospitality.share_group; unlink hospitality.link.reservation_in_share_group; modify hospitality.payment; modify hospitality.payment_request.", "operationId": "apply_hospitality_action_check_out", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allow_open_balance": { "title": "Close out even if the folio balance is non-zero (vendor-mirror loads)", "type": "boolean" }, "departure_actual": { "format": "date-time", "title": "Actual departure", "type": "string" }, "reservation_room_ids": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation_room" }, "title": "Legs to check out (default: every leg — the whole party)", "type": "array" } }, "required": [ "departure_actual" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.reservation_in_share_group" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.reservation", "hospitality.availability_day", "hospitality.reservation_room", "hospitality.stay", "hospitality.folio", "hospitality.access_credential", "hospitality.room", "hospitality.room_discrepancy", "hospitality.share_group", "hospitality.payment", "hospitality.payment_request" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.check_out:apply" ] } ], "summary": "Check out", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.check_out/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_check_out` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.check_out:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_check_out", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allow_open_balance": { "title": "Close out even if the folio balance is non-zero (vendor-mirror loads)", "type": "boolean" }, "departure_actual": { "format": "date-time", "title": "Actual departure", "type": "string" }, "reservation_room_ids": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation_room" }, "title": "Legs to check out (default: every leg — the whole party)", "type": "array" } }, "required": [ "departure_actual" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.reservation_in_share_group" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.reservation", "hospitality.availability_day", "hospitality.reservation_room", "hospitality.stay", "hospitality.folio", "hospitality.access_credential", "hospitality.room", "hospitality.room_discrepancy", "hospitality.share_group", "hospitality.payment", "hospitality.payment_request" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Check out (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.check_out/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_check_out`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_check_out", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allow_open_balance": { "title": "Close out even if the folio balance is non-zero (vendor-mirror loads)", "type": "boolean" }, "departure_actual": { "format": "date-time", "title": "Actual departure", "type": "string" }, "reservation_room_ids": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation_room" }, "title": "Legs to check out (default: every leg — the whole party)", "type": "array" } }, "required": [ "departure_actual" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Check out (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.check_out/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_check_out` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.check_out:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_check_out", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allow_open_balance": { "title": "Close out even if the folio balance is non-zero (vendor-mirror loads)", "type": "boolean" }, "departure_actual": { "format": "date-time", "title": "Actual departure", "type": "string" }, "reservation_room_ids": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation_room" }, "title": "Legs to check out (default: every leg — the whole party)", "type": "array" } }, "required": [ "departure_actual" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Check out (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.claim_lost_found_item/apply": { "post": { "description": "A guest has asked for a found item: link them as its claimant and mark it `claimed` (`claimed_at`); it waits to be handed back or sent. Name the guest (`person_id`) or a stay of the item's house (`stay_id`), whose reservation's guest is the claimant — so the floor can claim for the guest in a room without reading the guest's name. A claim by the same person again is a no-op; a claim by someone else re-points the claimant. A returned or disposed item is refused. Emits `lost_found_item.claimed`.\n\nEffects: modify hospitality.lost_found_item; link hospitality.link.lost_found_item_claimed_by; unlink hospitality.link.lost_found_item_claimed_by.", "operationId": "apply_hospitality_action_claim_lost_found_item", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "person_id": { "format": "uuid", "title": "The guest asking for it (or stay_id)", "type": "string", "x-aerandil-references": "hospitality.person" }, "stay_id": { "format": "uuid", "title": "A stay at the item's house whose guest is asking for it (or person_id)", "type": "string", "x-aerandil-references": "hospitality.stay" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.lost_found_item" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.lost_found_item_claimed_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.lost_found_item" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.claim_lost_found_item:apply" ] } ], "summary": "Claim lost & found item", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.claim_lost_found_item/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_claim_lost_found_item` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.claim_lost_found_item:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_claim_lost_found_item", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "person_id": { "format": "uuid", "title": "The guest asking for it (or stay_id)", "type": "string", "x-aerandil-references": "hospitality.person" }, "stay_id": { "format": "uuid", "title": "A stay at the item's house whose guest is asking for it (or person_id)", "type": "string", "x-aerandil-references": "hospitality.stay" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.lost_found_item" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.lost_found_item_claimed_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.lost_found_item" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Claim lost & found item (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.claim_lost_found_item/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_claim_lost_found_item`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_claim_lost_found_item", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "person_id": { "format": "uuid", "title": "The guest asking for it (or stay_id)", "type": "string", "x-aerandil-references": "hospitality.person" }, "stay_id": { "format": "uuid", "title": "A stay at the item's house whose guest is asking for it (or person_id)", "type": "string", "x-aerandil-references": "hospitality.stay" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.lost_found_item" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Claim lost & found item (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.claim_lost_found_item/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_claim_lost_found_item` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.claim_lost_found_item:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_claim_lost_found_item", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "person_id": { "format": "uuid", "title": "The guest asking for it (or stay_id)", "type": "string", "x-aerandil-references": "hospitality.person" }, "stay_id": { "format": "uuid", "title": "A stay at the item's house whose guest is asking for it (or person_id)", "type": "string", "x-aerandil-references": "hospitality.stay" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.lost_found_item" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Claim lost & found item (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.clear_rate_restrictions/apply": { "post": { "description": "Open a date window back up: every restriction reachable from the given scope(s) that intersects the window is spliced — deleted when the window swallows it, trimmed when it overhangs an edge, split into two rows when the window falls strictly inside it. The store stays canonical (no 'open' override rows shadowing 'closed' ones, the OPERA open-restriction shape this deliberately rejects), and the event log keeps the full author/splice history.\n\nEffects: delete hospitality.rate_restriction; modify hospitality.rate_restriction; create hospitality.rate_restriction; link hospitality.link.room_type_has_restriction; link hospitality.link.rate_plan_has_restriction.\n\nStep-up: a person (a `User` principal) needs a fresh desk step-up proof — Clearing restrictions deletes every one the named scope reaches in the window — or the call is refused `403 step_up_required` before anything runs. Re-enter the passcode at `POST /v1/desk/sessions/{id}/passcode` and retry. Machine principals are not gated.", "operationId": "apply_hospitality_action_clear_rate_restrictions", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "end_date": { "format": "date", "title": "End date (inclusive)", "type": "string" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan scope (at least one of room_type_id / rate_plan_id)", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type scope (at least one of room_type_id / rate_plan_id)", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "start_date": { "format": "date", "title": "Start date", "type": "string" } }, "required": [ "start_date", "end_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.room_type_has_restriction", "hospitality.link.rate_plan_has_restriction" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "deleted", "modified", "created" ] }, "object_type": { "enum": [ "hospitality.rate_restriction" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "403": { "description": "`step_up_required` — a person applied this without a fresh desk step-up proof; nothing ran." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.clear_rate_restrictions:apply" ] } ], "summary": "Clear rate restrictions", "tags": [ "distribution" ], "x-aerandil-step-up": { "reason": "Clearing restrictions deletes every one the named scope reaches in the window" } } }, "/v1/actions/hospitality.action.clear_rate_restrictions/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_clear_rate_restrictions` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.clear_rate_restrictions:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_clear_rate_restrictions", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "end_date": { "format": "date", "title": "End date (inclusive)", "type": "string" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan scope (at least one of room_type_id / rate_plan_id)", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type scope (at least one of room_type_id / rate_plan_id)", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "start_date": { "format": "date", "title": "Start date", "type": "string" } }, "required": [ "start_date", "end_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.room_type_has_restriction", "hospitality.link.rate_plan_has_restriction" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "deleted", "modified", "created" ] }, "object_type": { "enum": [ "hospitality.rate_restriction" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Clear rate restrictions (dry-run)", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.clear_rate_restrictions/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_clear_rate_restrictions`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_clear_rate_restrictions", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "end_date": { "format": "date", "title": "End date (inclusive)", "type": "string" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan scope (at least one of room_type_id / rate_plan_id)", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type scope (at least one of room_type_id / rate_plan_id)", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "start_date": { "format": "date", "title": "Start date", "type": "string" } }, "required": [ "start_date", "end_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Clear rate restrictions (dry-run)", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.clear_rate_restrictions/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_clear_rate_restrictions` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.clear_rate_restrictions:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_clear_rate_restrictions", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "end_date": { "format": "date", "title": "End date (inclusive)", "type": "string" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan scope (at least one of room_type_id / rate_plan_id)", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type scope (at least one of room_type_id / rate_plan_id)", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "start_date": { "format": "date", "title": "Start date", "type": "string" } }, "required": [ "start_date", "end_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Clear rate restrictions (rollup delta)", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.clear_table/apply": { "post": { "description": "The table is bussed and reset: a `dirty` service table — marked dirty when its check settled — goes back to `available`, so the floor plan can seat it again (Toast's and Simphony's table status after bussing). Idempotent on an available table; any other status (seated, reserved, blocked) is refused — a seated table clears by settling its check.\n\nEffects: modify hospitality.service_table.", "operationId": "apply_hospitality_action_clear_table", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_table" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.service_table" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.clear_table:apply" ] } ], "summary": "Clear table", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.clear_table/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_clear_table` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.clear_table:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_clear_table", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_table" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.service_table" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Clear table (dry-run)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.clear_table/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_clear_table`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_clear_table", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_table" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Clear table (dry-run)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.clear_table/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_clear_table` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.clear_table:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_clear_table", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_table" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Clear table (rollup delta)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.clock_in/apply": { "post": { "description": "Open a worked shift for the target staff member. `department` and the management/non-management split are stamped at clock-in (a cross-department day is two shifts; a later promotion does not rewrite history). Refused while the member already has an open shift or is inactive.\n\nEffects: create hospitality.staff_shift; link hospitality.link.shift_for_staff_member; link hospitality.link.shift_at_property.", "operationId": "apply_hospitality_action_clock_in", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "actual_start": { "format": "date-time", "title": "Actual start (defaults to now)", "type": "string" }, "credit_target": { "format": "decimal", "title": "Housekeeping credits the attendant is expected to clean this shift (optional; settable later with set_shift_credit_target)", "type": "string" }, "department": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "it_services", "retail", "other_operated", "minor_operated", "administrative_general", "information_telecom_systems", "sales_marketing", "property_ops_maintenance", "utilities" ], "title": "USALI 12 Schedule 15 department", "type": "string" }, "property_id": { "format": "uuid", "title": "Property the shift is worked at", "type": "string", "x-aerandil-references": "hospitality.property" }, "scheduled_end": { "format": "date-time", "title": "Scheduled end (optional)", "type": "string" }, "scheduled_start": { "format": "date-time", "title": "Scheduled start (optional)", "type": "string" }, "source": { "enum": [ "timeclock", "payroll_import", "manual" ], "title": "Provenance (defaults to `timeclock`)", "type": "string" } }, "required": [ "property_id", "department" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.shift_for_staff_member", "hospitality.link.shift_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.staff_shift" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.clock_in:apply" ] } ], "summary": "Clock in", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.clock_in/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_clock_in` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.clock_in:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_clock_in", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "actual_start": { "format": "date-time", "title": "Actual start (defaults to now)", "type": "string" }, "credit_target": { "format": "decimal", "title": "Housekeeping credits the attendant is expected to clean this shift (optional; settable later with set_shift_credit_target)", "type": "string" }, "department": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "it_services", "retail", "other_operated", "minor_operated", "administrative_general", "information_telecom_systems", "sales_marketing", "property_ops_maintenance", "utilities" ], "title": "USALI 12 Schedule 15 department", "type": "string" }, "property_id": { "format": "uuid", "title": "Property the shift is worked at", "type": "string", "x-aerandil-references": "hospitality.property" }, "scheduled_end": { "format": "date-time", "title": "Scheduled end (optional)", "type": "string" }, "scheduled_start": { "format": "date-time", "title": "Scheduled start (optional)", "type": "string" }, "source": { "enum": [ "timeclock", "payroll_import", "manual" ], "title": "Provenance (defaults to `timeclock`)", "type": "string" } }, "required": [ "property_id", "department" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.shift_for_staff_member", "hospitality.link.shift_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.staff_shift" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Clock in (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.clock_in/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_clock_in`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_clock_in", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "actual_start": { "format": "date-time", "title": "Actual start (defaults to now)", "type": "string" }, "credit_target": { "format": "decimal", "title": "Housekeeping credits the attendant is expected to clean this shift (optional; settable later with set_shift_credit_target)", "type": "string" }, "department": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "it_services", "retail", "other_operated", "minor_operated", "administrative_general", "information_telecom_systems", "sales_marketing", "property_ops_maintenance", "utilities" ], "title": "USALI 12 Schedule 15 department", "type": "string" }, "property_id": { "format": "uuid", "title": "Property the shift is worked at", "type": "string", "x-aerandil-references": "hospitality.property" }, "scheduled_end": { "format": "date-time", "title": "Scheduled end (optional)", "type": "string" }, "scheduled_start": { "format": "date-time", "title": "Scheduled start (optional)", "type": "string" }, "source": { "enum": [ "timeclock", "payroll_import", "manual" ], "title": "Provenance (defaults to `timeclock`)", "type": "string" } }, "required": [ "property_id", "department" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Clock in (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.clock_in/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_clock_in` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.clock_in:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_clock_in", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "actual_start": { "format": "date-time", "title": "Actual start (defaults to now)", "type": "string" }, "credit_target": { "format": "decimal", "title": "Housekeeping credits the attendant is expected to clean this shift (optional; settable later with set_shift_credit_target)", "type": "string" }, "department": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "it_services", "retail", "other_operated", "minor_operated", "administrative_general", "information_telecom_systems", "sales_marketing", "property_ops_maintenance", "utilities" ], "title": "USALI 12 Schedule 15 department", "type": "string" }, "property_id": { "format": "uuid", "title": "Property the shift is worked at", "type": "string", "x-aerandil-references": "hospitality.property" }, "scheduled_end": { "format": "date-time", "title": "Scheduled end (optional)", "type": "string" }, "scheduled_start": { "format": "date-time", "title": "Scheduled start (optional)", "type": "string" }, "source": { "enum": [ "timeclock", "payroll_import", "manual" ], "title": "Provenance (defaults to `timeclock`)", "type": "string" } }, "required": [ "property_id", "department" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Clock in (rollup delta)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.clock_out/apply": { "post": { "description": "Close the target open shift. Computes `worked_hours` (`actual_end - actual_start` minus unpaid break, decimals preserved per Schedule 15) and stamps the property-local `business_date` from `actual_start`. Emits `labour.shift_closed.recorded` for the `daily_labour` projection.\n\nEffects: modify hospitality.staff_shift.", "operationId": "apply_hospitality_action_clock_out", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "actual_end": { "format": "date-time", "title": "Actual end (defaults to now)", "type": "string" }, "unpaid_break_minutes": { "title": "Unpaid break minutes (defaults to 0)", "type": "integer" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_shift" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.staff_shift" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.clock_out:apply" ] } ], "summary": "Clock out", "tags": [ "labour" ] } }, "/v1/actions/hospitality.action.clock_out/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_clock_out` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.clock_out:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_clock_out", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "actual_end": { "format": "date-time", "title": "Actual end (defaults to now)", "type": "string" }, "unpaid_break_minutes": { "title": "Unpaid break minutes (defaults to 0)", "type": "integer" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_shift" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.staff_shift" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Clock out (dry-run)", "tags": [ "labour" ] } }, "/v1/actions/hospitality.action.clock_out/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_clock_out`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_clock_out", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "actual_end": { "format": "date-time", "title": "Actual end (defaults to now)", "type": "string" }, "unpaid_break_minutes": { "title": "Unpaid break minutes (defaults to 0)", "type": "integer" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_shift" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Clock out (dry-run)", "tags": [ "labour" ] } }, "/v1/actions/hospitality.action.clock_out/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_clock_out` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.clock_out:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_clock_out", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "actual_end": { "format": "date-time", "title": "Actual end (defaults to now)", "type": "string" }, "unpaid_break_minutes": { "title": "Unpaid break minutes (defaults to 0)", "type": "integer" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_shift" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Clock out (rollup delta)", "tags": [ "labour" ] } }, "/v1/actions/hospitality.action.close_agent_thread/apply": { "post": { "description": "Close an open `agent_thread`. Terminal for appends — reopening is a deliberate future action, not a status flip. Closing an already-closed thread is rejected. Emits `agent_thread.closed`.\n\nEffects: modify hospitality.agent_thread.", "operationId": "apply_hospitality_action_close_agent_thread", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_thread" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.agent_thread" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.close_agent_thread:apply" ] } ], "summary": "Close agent thread", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.close_agent_thread/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_close_agent_thread` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.close_agent_thread:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_close_agent_thread", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_thread" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.agent_thread" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Close agent thread (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.close_agent_thread/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_close_agent_thread`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_close_agent_thread", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_thread" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Close agent thread (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.close_agent_thread/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_close_agent_thread` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.close_agent_thread:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_close_agent_thread", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_thread" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Close agent thread (rollup delta)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.close_cashier_session/apply": { "post": { "description": "Close a shift against the operator's count. Expected = opening float + cash in - cash out over the session's movements; variance = counted - expected, recorded as declared data (the over/short) — never a GL posting, because no benchmark vendor verifiably posts one. Closed is immutable: re-closing with the same count is a no-op, a different count refuses, and corrections are compensating entries in the next session. The close never gates the business date — the night audit only counts open sessions as an exception signal.\n\nEffects: modify hospitality.cashier_session.", "operationId": "apply_hospitality_action_close_cashier_session", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "closed_at": { "format": "date-time", "title": "Shift end (business time; defaults to now)", "type": "string" }, "counted_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Counted drawer total", "type": "object" } }, "required": [ "counted_amount" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.cashier_session" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.cashier_session" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.close_cashier_session:apply" ] } ], "summary": "Close cashier session", "tags": [ "cashiering" ] } }, "/v1/actions/hospitality.action.close_cashier_session/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_close_cashier_session` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.close_cashier_session:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_close_cashier_session", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "closed_at": { "format": "date-time", "title": "Shift end (business time; defaults to now)", "type": "string" }, "counted_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Counted drawer total", "type": "object" } }, "required": [ "counted_amount" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.cashier_session" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.cashier_session" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Close cashier session (dry-run)", "tags": [ "cashiering" ] } }, "/v1/actions/hospitality.action.close_cashier_session/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_close_cashier_session`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_close_cashier_session", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "closed_at": { "format": "date-time", "title": "Shift end (business time; defaults to now)", "type": "string" }, "counted_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Counted drawer total", "type": "object" } }, "required": [ "counted_amount" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.cashier_session" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Close cashier session (dry-run)", "tags": [ "cashiering" ] } }, "/v1/actions/hospitality.action.close_cashier_session/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_close_cashier_session` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.close_cashier_session:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_close_cashier_session", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "closed_at": { "format": "date-time", "title": "Shift end (business time; defaults to now)", "type": "string" }, "counted_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Counted drawer total", "type": "object" } }, "required": [ "counted_amount" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.cashier_session" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Close cashier session (rollup delta)", "tags": [ "cashiering" ] } }, "/v1/actions/hospitality.action.close_channel_connection/apply": { "post": { "description": "Terminal end of a conduit — the property stopped distributing through this partner. Publication stops and inbound reservations are rejected as `connection_inactive` rather than silently dropped, because a partner still holding the connection open needs a definite answer. Soft-delete stays the ontology-wide contract; `closed` is the domain-level end state. Emits `channel_connection.closed`.\n\nEffects: modify hospitality.channel_connection.", "operationId": "apply_hospitality_action_close_channel_connection", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "notes": { "title": "Why the conduit was closed", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.channel_connection" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.close_channel_connection:apply" ] } ], "summary": "Close channel connection", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.close_channel_connection/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_close_channel_connection` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.close_channel_connection:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_close_channel_connection", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "notes": { "title": "Why the conduit was closed", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.channel_connection" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Close channel connection (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.close_channel_connection/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_close_channel_connection`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_close_channel_connection", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "notes": { "title": "Why the conduit was closed", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Close channel connection (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.close_channel_connection/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_close_channel_connection` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.close_channel_connection:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_close_channel_connection", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "notes": { "title": "Why the conduit was closed", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Close channel connection (rollup delta)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.close_folio/apply": { "post": { "description": "Close an open folio through the zero-balance discipline — the generic close for folios `check_out` does not own: rebate folios, reopened guest folios, house accounts. Refuses a non-zero balance (settle it first) and a folio whose stay is still in-house (that close belongs to `check_out`). Re-applying to a closed folio is a no-op.\n\nEffects: modify hospitality.folio.", "operationId": "apply_hospitality_action_close_folio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.close_folio:apply" ] } ], "summary": "Close folio", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.close_folio/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_close_folio` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.close_folio:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_close_folio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Close folio (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.close_folio/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_close_folio`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_close_folio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Close folio (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.close_folio/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_close_folio` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.close_folio:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_close_folio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Close folio (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.close_guest_feedback/apply": { "post": { "description": "Finish a case: it goes `closed` and takes nothing more. A resolved case, a compliment or a suggestion closes as it is; a complaint closed without being resolved needs the `reason` (the guest withdrew it, could not be reached). Closing a closed case is a no-op. Emits `guest_feedback.closed`.\n\nEffects: modify hospitality.guest_feedback.", "operationId": "apply_hospitality_action_close_guest_feedback", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why it is closed (required for an unresolved complaint)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.guest_feedback" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.close_guest_feedback:apply" ] } ], "summary": "Close guest feedback", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.close_guest_feedback/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_close_guest_feedback` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.close_guest_feedback:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_close_guest_feedback", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why it is closed (required for an unresolved complaint)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.guest_feedback" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Close guest feedback (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.close_guest_feedback/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_close_guest_feedback`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_close_guest_feedback", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why it is closed (required for an unresolved complaint)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Close guest feedback (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.close_guest_feedback/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_close_guest_feedback` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.close_guest_feedback:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_close_guest_feedback", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why it is closed (required for an unresolved complaint)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Close guest feedback (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.close_pattern_detection_run/apply": { "post": { "description": "Mark a recovery_pattern_detection_run terminal (completed or failed) once its assessments are dispositioned.\n\nEffects: modify hospitality.recovery_pattern_detection_run.", "operationId": "apply_hospitality_action_close_pattern_detection_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "failure_reason": { "title": "Failure reason when status = failed", "type": "string" }, "status": { "enum": [ "in_progress", "completed", "failed" ], "title": "Terminal run status", "type": "string" } }, "required": [ "status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.recovery_pattern_detection_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.recovery_pattern_detection_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.close_pattern_detection_run:apply" ] } ], "summary": "Close pattern detection run", "tags": [ "recovery_pattern_detection" ] } }, "/v1/actions/hospitality.action.close_pattern_detection_run/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_close_pattern_detection_run` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.close_pattern_detection_run:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_close_pattern_detection_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "failure_reason": { "title": "Failure reason when status = failed", "type": "string" }, "status": { "enum": [ "in_progress", "completed", "failed" ], "title": "Terminal run status", "type": "string" } }, "required": [ "status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.recovery_pattern_detection_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.recovery_pattern_detection_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Close pattern detection run (dry-run)", "tags": [ "recovery_pattern_detection" ] } }, "/v1/actions/hospitality.action.close_pattern_detection_run/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_close_pattern_detection_run`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_close_pattern_detection_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "failure_reason": { "title": "Failure reason when status = failed", "type": "string" }, "status": { "enum": [ "in_progress", "completed", "failed" ], "title": "Terminal run status", "type": "string" } }, "required": [ "status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.recovery_pattern_detection_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Close pattern detection run (dry-run)", "tags": [ "recovery_pattern_detection" ] } }, "/v1/actions/hospitality.action.close_pattern_detection_run/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_close_pattern_detection_run` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.close_pattern_detection_run:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_close_pattern_detection_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "failure_reason": { "title": "Failure reason when status = failed", "type": "string" }, "status": { "enum": [ "in_progress", "completed", "failed" ], "title": "Terminal run status", "type": "string" } }, "required": [ "status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.recovery_pattern_detection_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Close pattern detection run (rollup delta)", "tags": [ "recovery_pattern_detection" ] } }, "/v1/actions/hospitality.action.close_staff_employment_period/apply": { "post": { "description": "Close the staff member's current open employment period. Updates `staff_member.active = false` when no successor period is opened in the same transaction.\n\nEffects: modify hospitality.staff_employment_period; modify hospitality.staff_member.", "operationId": "apply_hospitality_action_close_staff_employment_period", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "termination_date": { "format": "date", "title": "Termination date", "type": "string" }, "termination_reason": { "enum": [ "voluntary", "involuntary", "retirement", "transfer", "end_of_season", "other" ], "title": "Termination reason", "type": "string" } }, "required": [ "termination_date", "termination_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_employment_period" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.staff_employment_period", "hospitality.staff_member" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.close_staff_employment_period:apply" ] } ], "summary": "Close staff employment period", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.close_staff_employment_period/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_close_staff_employment_period` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.close_staff_employment_period:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_close_staff_employment_period", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "termination_date": { "format": "date", "title": "Termination date", "type": "string" }, "termination_reason": { "enum": [ "voluntary", "involuntary", "retirement", "transfer", "end_of_season", "other" ], "title": "Termination reason", "type": "string" } }, "required": [ "termination_date", "termination_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_employment_period" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.staff_employment_period", "hospitality.staff_member" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Close staff employment period (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.close_staff_employment_period/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_close_staff_employment_period`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_close_staff_employment_period", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "termination_date": { "format": "date", "title": "Termination date", "type": "string" }, "termination_reason": { "enum": [ "voluntary", "involuntary", "retirement", "transfer", "end_of_season", "other" ], "title": "Termination reason", "type": "string" } }, "required": [ "termination_date", "termination_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_employment_period" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Close staff employment period (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.close_staff_employment_period/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_close_staff_employment_period` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.close_staff_employment_period:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_close_staff_employment_period", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "termination_date": { "format": "date", "title": "Termination date", "type": "string" }, "termination_reason": { "enum": [ "voluntary", "involuntary", "retirement", "transfer", "end_of_season", "other" ], "title": "Termination reason", "type": "string" } }, "required": [ "termination_date", "termination_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_employment_period" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Close staff employment period (rollup delta)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.collect_tray/apply": { "post": { "description": "The tray or trolley comes back from the room: the target room-service check's `delivery_status` goes `delivered` → `cleared`, stamping `cleared_at`, and the order leaves the room-service board. Only from `delivered`; the check may still be open. Emits `fnb.tray_collected`.\n\nEffects: modify hospitality.guest_check.", "operationId": "apply_hospitality_action_collect_tray", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.guest_check" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.collect_tray:apply" ] } ], "summary": "Collect tray", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.collect_tray/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_collect_tray` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.collect_tray:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_collect_tray", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.guest_check" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Collect tray (dry-run)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.collect_tray/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_collect_tray`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_collect_tray", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Collect tray (dry-run)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.collect_tray/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_collect_tray` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.collect_tray:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_collect_tray", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Collect tray (rollup delta)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.combine_reservations_as_share/apply": { "post": { "description": "Combine two pre-arrival, single-room, same-room-type reservations at one property into a share: both parties occupy one physical room, each keeping its own reservation, folios, and independent check-in/check-out (OPERA's share model). The joining stay must overlap the group's covered dates by at least one night; every overlapping night releases one room-night back to the availability ledger — that release is how one room is deducted regardless of sharer count, while non-overlapping wing nights stay consumed. Distribution full keeps every member's booked rates; split (two members max) divides the primary's rate per shared night, remainder to the joiner. Re-invoking with the same primary adds further members to its group.\n\nEffects: create hospitality.share_group; link hospitality.link.share_group_at_property; link hospitality.link.reservation_in_share_group; modify hospitality.availability_day; modify hospitality.reservation_night.", "operationId": "apply_hospitality_action_combine_reservations_as_share", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "distribution": { "enum": [ "full", "split" ], "title": "Rate distribution (full or split)", "type": "string" }, "joining_reservation_id": { "format": "uuid", "title": "The reservation joining the share", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "primary_reservation_id": { "format": "uuid", "title": "The anchor reservation (split's rate basis)", "type": "string", "x-aerandil-references": "hospitality.reservation" } }, "required": [ "primary_reservation_id", "joining_reservation_id", "distribution" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.share_group_at_property", "hospitality.link.reservation_in_share_group" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.share_group", "hospitality.availability_day", "hospitality.reservation_night" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.combine_reservations_as_share:apply" ] } ], "summary": "Combine reservations as share", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.combine_reservations_as_share/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_combine_reservations_as_share` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.combine_reservations_as_share:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_combine_reservations_as_share", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "distribution": { "enum": [ "full", "split" ], "title": "Rate distribution (full or split)", "type": "string" }, "joining_reservation_id": { "format": "uuid", "title": "The reservation joining the share", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "primary_reservation_id": { "format": "uuid", "title": "The anchor reservation (split's rate basis)", "type": "string", "x-aerandil-references": "hospitality.reservation" } }, "required": [ "primary_reservation_id", "joining_reservation_id", "distribution" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.share_group_at_property", "hospitality.link.reservation_in_share_group" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.share_group", "hospitality.availability_day", "hospitality.reservation_night" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Combine reservations as share (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.combine_reservations_as_share/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_combine_reservations_as_share`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_combine_reservations_as_share", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "distribution": { "enum": [ "full", "split" ], "title": "Rate distribution (full or split)", "type": "string" }, "joining_reservation_id": { "format": "uuid", "title": "The reservation joining the share", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "primary_reservation_id": { "format": "uuid", "title": "The anchor reservation (split's rate basis)", "type": "string", "x-aerandil-references": "hospitality.reservation" } }, "required": [ "primary_reservation_id", "joining_reservation_id", "distribution" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Combine reservations as share (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.combine_reservations_as_share/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_combine_reservations_as_share` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.combine_reservations_as_share:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_combine_reservations_as_share", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "distribution": { "enum": [ "full", "split" ], "title": "Rate distribution (full or split)", "type": "string" }, "joining_reservation_id": { "format": "uuid", "title": "The reservation joining the share", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "primary_reservation_id": { "format": "uuid", "title": "The anchor reservation (split's rate basis)", "type": "string", "x-aerandil-references": "hospitality.reservation" } }, "required": [ "primary_reservation_id", "joining_reservation_id", "distribution" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Combine reservations as share (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.comp_check_line/apply": { "post": { "description": "Write off a FIRED or FULFILLED line — product was made and delivered, so this hits food cost and is excluded from the settled total. Carries a reason and the authorising staff member — whoever is signed in (the session's staff member, recorded as `comp_authorised_by`), never one named in the body: a body `authorised_by` must be that same staff member or the comp is refused (`comp_not_authenticated: …`); a caller that is no member of staff records none. When a `comp_authority_policy` row exists for (role, food_beverage) and the line value exceeds its per-incident limit, the line posts with `comp_escalation_required = true` rather than blocking service — the soft-escalation posture the policy object documents. The line's modifier lines are comped with it (their value counts toward the limit); a modifier line is never comped alone. The check's totals drop by what was comped. Emits `fnb.line_comped`.\n\nEffects: modify hospitality.check_line; modify hospitality.guest_check.", "operationId": "apply_hospitality_action_comp_check_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "authorised_by": { "format": "uuid", "title": "The staff member authorising the comp — must be the one signed in (optional; the session's staff member is recorded either way)", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "reason": { "title": "Why the line is being comped (kitchen error, guest recovery, staff meal …)", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.check_line" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.check_line", "hospitality.guest_check" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.comp_check_line:apply" ] } ], "summary": "Comp check line", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.comp_check_line/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_comp_check_line` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.comp_check_line:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_comp_check_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "authorised_by": { "format": "uuid", "title": "The staff member authorising the comp — must be the one signed in (optional; the session's staff member is recorded either way)", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "reason": { "title": "Why the line is being comped (kitchen error, guest recovery, staff meal …)", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.check_line" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.check_line", "hospitality.guest_check" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Comp check line (dry-run)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.comp_check_line/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_comp_check_line`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_comp_check_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "authorised_by": { "format": "uuid", "title": "The staff member authorising the comp — must be the one signed in (optional; the session's staff member is recorded either way)", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "reason": { "title": "Why the line is being comped (kitchen error, guest recovery, staff meal …)", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.check_line" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Comp check line (dry-run)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.comp_check_line/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_comp_check_line` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.comp_check_line:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_comp_check_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "authorised_by": { "format": "uuid", "title": "The staff member authorising the comp — must be the one signed in (optional; the session's staff member is recorded either way)", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "reason": { "title": "Why the line is being comped (kitchen error, guest recovery, staff meal …)", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.check_line" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Comp check line (rollup delta)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.complete_appointment/apply": { "post": { "description": "The treatment ended: checked_in / in_service → completed. Money is not resolved here — the desk (or the folio, for in-house guests) settles via settle_appointment; the completed/settled split mirrors the spa-floor reality that the treatment ends in the room and payment happens at the desk. Business time: `completed_at` defaults to now. Emits `spa.appointment_completed`.\n\nEffects: modify hospitality.appointment.", "operationId": "apply_hospitality_action_complete_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "completed_at": { "format": "date-time", "title": "When the treatment ended (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.appointment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.complete_appointment:apply" ] } ], "summary": "Complete appointment", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.complete_appointment/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_complete_appointment` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.complete_appointment:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_complete_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "completed_at": { "format": "date-time", "title": "When the treatment ended (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.appointment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Complete appointment (dry-run)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.complete_appointment/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_complete_appointment`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_complete_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "completed_at": { "format": "date-time", "title": "When the treatment ended (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Complete appointment (dry-run)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.complete_appointment/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_complete_appointment` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.complete_appointment:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_complete_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "completed_at": { "format": "date-time", "title": "When the treatment ended (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Complete appointment (rollup delta)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.complete_channel_publication/apply": { "post": { "description": "Close a `running` publication run with its outcome and counts. `partial` is a real outcome, not a rounding of success or failure: a run that published four hundred date-cells and had eleven refused for an unmapped rate plan is neither, and flattening it loses the only signal that mapping is broken. `error_summary` is required for `failed` and `partial`. Cells and messages are counted separately because bundling makes them diverge — the same changed cells are one message or forty depending on how well consecutive dates collapsed, and the partner's load is measured in messages while ours is measured in cells. Emits `channel_publication.completed`.\n\nEffects: modify hospitality.channel_publication_run.", "operationId": "apply_hospitality_action_complete_channel_publication", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cells_published": { "title": "Date-cells successfully published across all facets", "type": "integer" }, "cells_rejected": { "title": "Date-cells the partner refused", "type": "integer" }, "error_summary": { "title": "Why the run failed or was partial (required for those outcomes)", "type": "string" }, "messages_sent": { "title": "Wire messages sent", "type": "integer" }, "outcome": { "enum": [ "succeeded", "partial", "failed", "cancelled" ], "title": "Terminal status for the run", "type": "string" } }, "required": [ "outcome" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_publication_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.channel_publication_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.complete_channel_publication:apply" ] } ], "summary": "Complete channel publication", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.complete_channel_publication/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_complete_channel_publication` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.complete_channel_publication:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_complete_channel_publication", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cells_published": { "title": "Date-cells successfully published across all facets", "type": "integer" }, "cells_rejected": { "title": "Date-cells the partner refused", "type": "integer" }, "error_summary": { "title": "Why the run failed or was partial (required for those outcomes)", "type": "string" }, "messages_sent": { "title": "Wire messages sent", "type": "integer" }, "outcome": { "enum": [ "succeeded", "partial", "failed", "cancelled" ], "title": "Terminal status for the run", "type": "string" } }, "required": [ "outcome" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_publication_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.channel_publication_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Complete channel publication (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.complete_channel_publication/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_complete_channel_publication`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_complete_channel_publication", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cells_published": { "title": "Date-cells successfully published across all facets", "type": "integer" }, "cells_rejected": { "title": "Date-cells the partner refused", "type": "integer" }, "error_summary": { "title": "Why the run failed or was partial (required for those outcomes)", "type": "string" }, "messages_sent": { "title": "Wire messages sent", "type": "integer" }, "outcome": { "enum": [ "succeeded", "partial", "failed", "cancelled" ], "title": "Terminal status for the run", "type": "string" } }, "required": [ "outcome" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_publication_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Complete channel publication (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.complete_channel_publication/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_complete_channel_publication` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.complete_channel_publication:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_complete_channel_publication", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cells_published": { "title": "Date-cells successfully published across all facets", "type": "integer" }, "cells_rejected": { "title": "Date-cells the partner refused", "type": "integer" }, "error_summary": { "title": "Why the run failed or was partial (required for those outcomes)", "type": "string" }, "messages_sent": { "title": "Wire messages sent", "type": "integer" }, "outcome": { "enum": [ "succeeded", "partial", "failed", "cancelled" ], "title": "Terminal status for the run", "type": "string" } }, "required": [ "outcome" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_publication_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Complete channel publication (rollup delta)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.complete_connector_sync/apply": { "post": { "description": "Close a `running` sync run with its outcome and counts: records pulled from the source, landed in raw staging, and rejected by ontology validation at the map/load hop. `error_summary` is required when the outcome is `failed`. `cursor_window` records the per-stream from→to window for audit; the live cursors the next run resumes from stay in the staging schema. Emits `connector.sync_completed`.\n\nEffects: modify hospitality.connector_sync_run.", "operationId": "apply_hospitality_action_complete_connector_sync", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cursor_window": { "title": "Per-stream cursor window this run covered (JSON summary)" }, "error_summary": { "title": "Terminal failure summary (required when outcome = failed)", "type": "string" }, "outcome": { "enum": [ "succeeded", "failed", "cancelled" ], "title": "Terminal status for the run", "type": "string" }, "records_landed": { "title": "Records upserted into raw staging", "type": "integer" }, "records_pulled": { "title": "Records extracted from the source system", "type": "integer" }, "records_rejected": { "title": "Records refused by ontology validation", "type": "integer" } }, "required": [ "outcome" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector_sync_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.connector_sync_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.complete_connector_sync:apply" ] } ], "summary": "Complete connector sync", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.complete_connector_sync/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_complete_connector_sync` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.complete_connector_sync:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_complete_connector_sync", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cursor_window": { "title": "Per-stream cursor window this run covered (JSON summary)" }, "error_summary": { "title": "Terminal failure summary (required when outcome = failed)", "type": "string" }, "outcome": { "enum": [ "succeeded", "failed", "cancelled" ], "title": "Terminal status for the run", "type": "string" }, "records_landed": { "title": "Records upserted into raw staging", "type": "integer" }, "records_pulled": { "title": "Records extracted from the source system", "type": "integer" }, "records_rejected": { "title": "Records refused by ontology validation", "type": "integer" } }, "required": [ "outcome" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector_sync_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.connector_sync_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Complete connector sync (dry-run)", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.complete_connector_sync/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_complete_connector_sync`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_complete_connector_sync", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cursor_window": { "title": "Per-stream cursor window this run covered (JSON summary)" }, "error_summary": { "title": "Terminal failure summary (required when outcome = failed)", "type": "string" }, "outcome": { "enum": [ "succeeded", "failed", "cancelled" ], "title": "Terminal status for the run", "type": "string" }, "records_landed": { "title": "Records upserted into raw staging", "type": "integer" }, "records_pulled": { "title": "Records extracted from the source system", "type": "integer" }, "records_rejected": { "title": "Records refused by ontology validation", "type": "integer" } }, "required": [ "outcome" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector_sync_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Complete connector sync (dry-run)", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.complete_connector_sync/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_complete_connector_sync` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.complete_connector_sync:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_complete_connector_sync", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cursor_window": { "title": "Per-stream cursor window this run covered (JSON summary)" }, "error_summary": { "title": "Terminal failure summary (required when outcome = failed)", "type": "string" }, "outcome": { "enum": [ "succeeded", "failed", "cancelled" ], "title": "Terminal status for the run", "type": "string" }, "records_landed": { "title": "Records upserted into raw staging", "type": "integer" }, "records_pulled": { "title": "Records extracted from the source system", "type": "integer" }, "records_rejected": { "title": "Records refused by ontology validation", "type": "integer" } }, "required": [ "outcome" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector_sync_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Complete connector sync (rollup delta)", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.complete_housekeeping_task/apply": { "post": { "description": "Mark a housekeeping task complete and update the room's status. Without `resulting_status`, only the unambiguous cascade runs: a departure / vacant_pickup / deep_clean / inspection completed against a dirty or pickup room promotes the cleaning axis to clean, and a stayover / turndown leaves it alone. With `resulting_status`, the attendant states the room's cleaning status at Finish (OPERA's Companion sets it at the same tap) and it is written in the same transaction, through the same refusal the status report applies: a room under an active out-of-order block today cannot have its cleaning status written — return_room_to_service decides. When the most specific active checklist template for the task's type and room type is `required_for_completion`, the task refuses to complete until a result for it is recorded (`record_checklist_result`). On an inspection task, `inspection_rating` (1–5) and `inspection_outcome` record the supervisor's verdict on the inspection and on the cleaning it rated — the most recent completed non-inspection task for the same room and business date, linked by `inspection_rates_task` (refused when there is none) — and a failed outcome mints a high-priority re-clean of the same type (`origin` reclean), linked by `housekeeping_task_from_inspection`. Without `resulting_status`, a passed inspection leaves the room inspected and a failed one dirty. A cleaning never needs an inspection to count. A runner's session may not state the room — neither `resulting_status` nor an inspection's verdict — and is refused (403): a room's condition is the word of the attendant who cleaned it and the supervisor who inspected it; a runner's finish leaves the room to the type-based cascade. A public area's task (2026-10-14) has no room to state: `resulting_status` is refused on it, and a `public_area_inspection`'s verdict rates the area's latest completed clean of the day and re-mints a failed one for the area, as a room's inspection does. A `minibar` or `laundry` task (2026-10-14) may carry what it `consumed` — catalogued materials and quantities. A minibar's are minibar products, consumed from the room's own minibar store or the house's default minibar cart and charged at their sale price (the house's minibar tax rules derived) through post_charge to the bill of the stay that was in the room at `completed_at` — when the minibar was checked, not when a queued finish lands (2026-10-17) — while it is in house; with nobody in house to charge (the room empty at the check, or its guest gone since) the stock is still consumed, uncharged, and `minibar.uncharged.recorded` hands the desk its late charge, naming that stay or the last to leave by the check, never a guest who arrived after it; in a shared room `stay_id` names whose bill (in house, and arrived by the check). A laundry's are issued from the house's default laundry store to the room. Any other task type refuses `consumed`. `self_rating` (2026-10-15, 1–5) is the attendant's own rating of the work, stored on the task beside — never instead of — the supervisor's `inspection_rating`; it states nothing about the room, so a runner may send it; refused on an inspection. A finish is the holder's (2026-10-17): an attendant, runner or engineer who does not hold a task a colleague holds is refused (403), while the housekeeping supervisor and the desk finish it on the holder's behalf; a task nobody holds, or a worker group's, is taken by the staff member who finishes it, as a start takes it (a non-member is refused, 403). `self_rating` is the holder's own word, refused (403) to anyone else — the supervisor, the desk, an agent. `expected_holder_id` names the holder the caller saw (a finish queued on a handset): refused (422) when someone else, a group or nobody holds the task by the time it lands.\n\nEffects: modify hospitality.housekeeping_task; modify hospitality.room; link hospitality.link.inspection_rates_task; link hospitality.link.housekeeping_task_from_inspection; create hospitality.housekeeping_task; link hospitality.link.housekeeping_task_for_room; link hospitality.link.housekeeping_task_from_triage; link hospitality.link.housekeeping_task_assigned_to; unlink hospitality.link.housekeeping_task_assigned_to_group; link hospitality.link.housekeeping_task_for_area; link hospitality.link.housekeeping_task_requested_by_stay; create hospitality.stock_movement; create hospitality.stock_level; modify hospitality.stock_level; link hospitality.link.stock_movement_for_level; link hospitality.link.stock_level_for_material; link hospitality.link.stock_level_in_store; link hospitality.link.stock_movement_recorded_by; link hospitality.link.stock_movement_for_housekeeping_task; link hospitality.link.stock_movement_for_room; create hospitality.charge; create hospitality.tax_application; link hospitality.link.folio_has_charge; link hospitality.link.charge_has_tax_application; link hospitality.link.charge_for_service_item; link hospitality.link.charge_at_outlet; modify hospitality.folio.", "operationId": "apply_hospitality_action_complete_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "completed_at": { "format": "date-time", "title": "Completed at", "type": "string" }, "consumed": { "items": { "properties": { "material_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "type": "string" } }, "required": [ "material_id", "quantity" ], "type": "object" }, "title": "Consumption", "type": "array" }, "expected_holder_id": { "format": "uuid", "title": "Who the caller saw holding it — refused when that has changed", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "inspection_outcome": { "enum": [ "passed", "failed" ], "title": "passed, or failed (re-opens the cleaning) — inspection tasks only", "type": "string" }, "inspection_rating": { "title": "Inspection score, 1 (poor) to 5 (excellent) — inspection tasks only", "type": "integer" }, "notes": { "title": "Notes", "type": "string" }, "resulting_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Cleaning status the room is left in (defaults to the type-based cascade)", "type": "string" }, "self_rating": { "title": "The attendant's own rating of the work, 1 (poor) to 5 (excellent) — not on an inspection", "type": "integer" }, "stay_id": { "format": "uuid", "title": "The in-house stay whose bill takes a minibar charge (a shared room only)", "type": "string", "x-aerandil-references": "hospitality.stay" } }, "required": [ "completed_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.inspection_rates_task", "hospitality.link.housekeeping_task_from_inspection", "hospitality.link.housekeeping_task_for_room", "hospitality.link.housekeeping_task_from_triage", "hospitality.link.housekeeping_task_assigned_to", "hospitality.link.housekeeping_task_assigned_to_group", "hospitality.link.housekeeping_task_for_area", "hospitality.link.housekeeping_task_requested_by_stay", "hospitality.link.stock_movement_for_level", "hospitality.link.stock_level_for_material", "hospitality.link.stock_level_in_store", "hospitality.link.stock_movement_recorded_by", "hospitality.link.stock_movement_for_housekeeping_task", "hospitality.link.stock_movement_for_room", "hospitality.link.folio_has_charge", "hospitality.link.charge_has_tax_application", "hospitality.link.charge_for_service_item", "hospitality.link.charge_at_outlet" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.housekeeping_task", "hospitality.room", "hospitality.stock_movement", "hospitality.stock_level", "hospitality.charge", "hospitality.tax_application", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.complete_housekeeping_task:apply" ] } ], "summary": "Complete task", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.complete_housekeeping_task/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_complete_housekeeping_task` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.complete_housekeeping_task:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_complete_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "completed_at": { "format": "date-time", "title": "Completed at", "type": "string" }, "consumed": { "items": { "properties": { "material_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "type": "string" } }, "required": [ "material_id", "quantity" ], "type": "object" }, "title": "Consumption", "type": "array" }, "expected_holder_id": { "format": "uuid", "title": "Who the caller saw holding it — refused when that has changed", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "inspection_outcome": { "enum": [ "passed", "failed" ], "title": "passed, or failed (re-opens the cleaning) — inspection tasks only", "type": "string" }, "inspection_rating": { "title": "Inspection score, 1 (poor) to 5 (excellent) — inspection tasks only", "type": "integer" }, "notes": { "title": "Notes", "type": "string" }, "resulting_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Cleaning status the room is left in (defaults to the type-based cascade)", "type": "string" }, "self_rating": { "title": "The attendant's own rating of the work, 1 (poor) to 5 (excellent) — not on an inspection", "type": "integer" }, "stay_id": { "format": "uuid", "title": "The in-house stay whose bill takes a minibar charge (a shared room only)", "type": "string", "x-aerandil-references": "hospitality.stay" } }, "required": [ "completed_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.inspection_rates_task", "hospitality.link.housekeeping_task_from_inspection", "hospitality.link.housekeeping_task_for_room", "hospitality.link.housekeeping_task_from_triage", "hospitality.link.housekeeping_task_assigned_to", "hospitality.link.housekeeping_task_assigned_to_group", "hospitality.link.housekeeping_task_for_area", "hospitality.link.housekeeping_task_requested_by_stay", "hospitality.link.stock_movement_for_level", "hospitality.link.stock_level_for_material", "hospitality.link.stock_level_in_store", "hospitality.link.stock_movement_recorded_by", "hospitality.link.stock_movement_for_housekeeping_task", "hospitality.link.stock_movement_for_room", "hospitality.link.folio_has_charge", "hospitality.link.charge_has_tax_application", "hospitality.link.charge_for_service_item", "hospitality.link.charge_at_outlet" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.housekeeping_task", "hospitality.room", "hospitality.stock_movement", "hospitality.stock_level", "hospitality.charge", "hospitality.tax_application", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Complete task (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.complete_housekeeping_task/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_complete_housekeeping_task`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_complete_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "completed_at": { "format": "date-time", "title": "Completed at", "type": "string" }, "consumed": { "items": { "properties": { "material_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "type": "string" } }, "required": [ "material_id", "quantity" ], "type": "object" }, "title": "Consumption", "type": "array" }, "expected_holder_id": { "format": "uuid", "title": "Who the caller saw holding it — refused when that has changed", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "inspection_outcome": { "enum": [ "passed", "failed" ], "title": "passed, or failed (re-opens the cleaning) — inspection tasks only", "type": "string" }, "inspection_rating": { "title": "Inspection score, 1 (poor) to 5 (excellent) — inspection tasks only", "type": "integer" }, "notes": { "title": "Notes", "type": "string" }, "resulting_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Cleaning status the room is left in (defaults to the type-based cascade)", "type": "string" }, "self_rating": { "title": "The attendant's own rating of the work, 1 (poor) to 5 (excellent) — not on an inspection", "type": "integer" }, "stay_id": { "format": "uuid", "title": "The in-house stay whose bill takes a minibar charge (a shared room only)", "type": "string", "x-aerandil-references": "hospitality.stay" } }, "required": [ "completed_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Complete task (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.complete_housekeeping_task/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_complete_housekeeping_task` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.complete_housekeeping_task:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_complete_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "completed_at": { "format": "date-time", "title": "Completed at", "type": "string" }, "consumed": { "items": { "properties": { "material_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "type": "string" } }, "required": [ "material_id", "quantity" ], "type": "object" }, "title": "Consumption", "type": "array" }, "expected_holder_id": { "format": "uuid", "title": "Who the caller saw holding it — refused when that has changed", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "inspection_outcome": { "enum": [ "passed", "failed" ], "title": "passed, or failed (re-opens the cleaning) — inspection tasks only", "type": "string" }, "inspection_rating": { "title": "Inspection score, 1 (poor) to 5 (excellent) — inspection tasks only", "type": "integer" }, "notes": { "title": "Notes", "type": "string" }, "resulting_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Cleaning status the room is left in (defaults to the type-based cascade)", "type": "string" }, "self_rating": { "title": "The attendant's own rating of the work, 1 (poor) to 5 (excellent) — not on an inspection", "type": "integer" }, "stay_id": { "format": "uuid", "title": "The in-house stay whose bill takes a minibar charge (a shared room only)", "type": "string", "x-aerandil-references": "hospitality.stay" } }, "required": [ "completed_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Complete task (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.complete_inspection_round/apply": { "post": { "description": "Finish an open round — hubOS's 'finalized by'. Refuses while any of the round's checkpoints has no result, or a recorded one has fewer photos (attachments whose upload landed) than `photo` items, naming them, unless `partial` is true with a `partial_reason` (the walk could not reach them); `observations` are the walker's on the round as a whole. Stamps `completed_at` (the handset's time when it says) and who finished it, clears the template's `open_round_id`, and moves the template on as a maintenance plan moves on: the next due date is the last plus the interval for a `fixed` template (skipping slots a late round overran) or the completion's property-local date plus the interval for a `floating` one. A retired template is not moved. Completing a completed round is a no-op; a cancelled one refuses. Emits `inspection_round.completed`.\n\nEffects: modify hospitality.inspection_round; modify hospitality.round_template; link hospitality.link.inspection_round_completed_by.", "operationId": "apply_hospitality_action_complete_inspection_round", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "completed_at": { "format": "date-time", "title": "When the round was finished (defaults to now; refused when more than five minutes ahead of the kernel's clock)", "type": "string" }, "observations": { "title": "The walker's observations on the round as a whole", "type": "string" }, "partial": { "title": "Finish with checkpoints unrecorded (needs partial_reason)", "type": "boolean" }, "partial_reason": { "title": "Why checkpoints were left unrecorded", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.inspection_round" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.inspection_round_completed_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.inspection_round", "hospitality.round_template" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.complete_inspection_round:apply" ] } ], "summary": "Complete inspection round", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.complete_inspection_round/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_complete_inspection_round` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.complete_inspection_round:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_complete_inspection_round", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "completed_at": { "format": "date-time", "title": "When the round was finished (defaults to now; refused when more than five minutes ahead of the kernel's clock)", "type": "string" }, "observations": { "title": "The walker's observations on the round as a whole", "type": "string" }, "partial": { "title": "Finish with checkpoints unrecorded (needs partial_reason)", "type": "boolean" }, "partial_reason": { "title": "Why checkpoints were left unrecorded", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.inspection_round" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.inspection_round_completed_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.inspection_round", "hospitality.round_template" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Complete inspection round (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.complete_inspection_round/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_complete_inspection_round`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_complete_inspection_round", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "completed_at": { "format": "date-time", "title": "When the round was finished (defaults to now; refused when more than five minutes ahead of the kernel's clock)", "type": "string" }, "observations": { "title": "The walker's observations on the round as a whole", "type": "string" }, "partial": { "title": "Finish with checkpoints unrecorded (needs partial_reason)", "type": "boolean" }, "partial_reason": { "title": "Why checkpoints were left unrecorded", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.inspection_round" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Complete inspection round (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.complete_inspection_round/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_complete_inspection_round` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.complete_inspection_round:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_complete_inspection_round", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "completed_at": { "format": "date-time", "title": "When the round was finished (defaults to now; refused when more than five minutes ahead of the kernel's clock)", "type": "string" }, "observations": { "title": "The walker's observations on the round as a whole", "type": "string" }, "partial": { "title": "Finish with checkpoints unrecorded (needs partial_reason)", "type": "boolean" }, "partial_reason": { "title": "Why checkpoints were left unrecorded", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.inspection_round" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Complete inspection round (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.complete_work_order/apply": { "post": { "description": "The work is done: terminal complete, with what was actually done recorded as the resolution. If the order holds an out-of-order block (work_order_holds_block), the block releases through its own release path — ledger rows restored, the room re-entering its declared return status (overridable here) — so finishing the repair and returning the room to inventory is one verb, never two writes to forget. A resolution is also written as the `resolution` line on the order's thread (2026-10-13), in the same transaction. Completing a postponed order clears the postponement. Re-completing a complete order is a no-op.\n\nEffects: modify hospitality.work_order; modify hospitality.room_status_block; modify hospitality.room; modify hospitality.availability_day; create hospitality.work_order_entry; link hospitality.link.work_order_entry_for_work_order; link hospitality.link.work_order_entry_recorded_by.", "operationId": "apply_hospitality_action_complete_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "resolution": { "title": "What was actually done", "type": "string" }, "resolved_at": { "format": "date-time", "title": "When the work finished (defaults to now)", "type": "string" }, "return_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Override the held block's declared return status", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.work_order_entry_for_work_order", "hospitality.link.work_order_entry_recorded_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.work_order", "hospitality.room_status_block", "hospitality.room", "hospitality.availability_day", "hospitality.work_order_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.complete_work_order:apply" ] } ], "summary": "Complete work order", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.complete_work_order/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_complete_work_order` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.complete_work_order:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_complete_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "resolution": { "title": "What was actually done", "type": "string" }, "resolved_at": { "format": "date-time", "title": "When the work finished (defaults to now)", "type": "string" }, "return_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Override the held block's declared return status", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.work_order_entry_for_work_order", "hospitality.link.work_order_entry_recorded_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.work_order", "hospitality.room_status_block", "hospitality.room", "hospitality.availability_day", "hospitality.work_order_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Complete work order (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.complete_work_order/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_complete_work_order`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_complete_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "resolution": { "title": "What was actually done", "type": "string" }, "resolved_at": { "format": "date-time", "title": "When the work finished (defaults to now)", "type": "string" }, "return_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Override the held block's declared return status", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Complete work order (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.complete_work_order/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_complete_work_order` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.complete_work_order:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_complete_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "resolution": { "title": "What was actually done", "type": "string" }, "resolved_at": { "format": "date-time", "title": "When the work finished (defaults to now)", "type": "string" }, "return_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Override the held block's declared return status", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Complete work order (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.configure_agent_installation_dispatch/apply": { "post": { "description": "Publish (or rotate) an installation's proposal 0022 dispatch surface: the receiver URL the dispatcher POSTs signed task envelopes to, the runtime's §8.3 identity URI, and its kid → base64 Ed25519 verification keys. Key rotation is additive — send old + new kid during the window. Endpoint URL follows the §6.1 rule (https, or http for loopback receivers only); key material must be public verification keys (RFC 8032 raw 32-byte, base64). Rejected on terminal (revoked/expired) installations. Emits `agent_installation.dispatch_configured`.\n\nEffects: modify hospitality.agent_installation.", "operationId": "apply_hospitality_action_configure_agent_installation_dispatch", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "dispatch_endpoint_url": { "title": "Receiver URL signed task envelopes POST to (§6.1)", "type": "string" }, "runner_identity_ref": { "title": "Stable §8.3 identity URI presented in signed acks/results", "type": "string" }, "runner_public_keys": { "additionalProperties": true, "title": "kid → base64 Ed25519 verification keys (JSON object)", "type": "object" } }, "required": [ "dispatch_endpoint_url", "runner_public_keys" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_installation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.agent_installation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.configure_agent_installation_dispatch:apply" ] } ], "summary": "Configure agent installation dispatch", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.configure_agent_installation_dispatch/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_configure_agent_installation_dispatch` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.configure_agent_installation_dispatch:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_configure_agent_installation_dispatch", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "dispatch_endpoint_url": { "title": "Receiver URL signed task envelopes POST to (§6.1)", "type": "string" }, "runner_identity_ref": { "title": "Stable §8.3 identity URI presented in signed acks/results", "type": "string" }, "runner_public_keys": { "additionalProperties": true, "title": "kid → base64 Ed25519 verification keys (JSON object)", "type": "object" } }, "required": [ "dispatch_endpoint_url", "runner_public_keys" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_installation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.agent_installation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Configure agent installation dispatch (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.configure_agent_installation_dispatch/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_configure_agent_installation_dispatch`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_configure_agent_installation_dispatch", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "dispatch_endpoint_url": { "title": "Receiver URL signed task envelopes POST to (§6.1)", "type": "string" }, "runner_identity_ref": { "title": "Stable §8.3 identity URI presented in signed acks/results", "type": "string" }, "runner_public_keys": { "additionalProperties": true, "title": "kid → base64 Ed25519 verification keys (JSON object)", "type": "object" } }, "required": [ "dispatch_endpoint_url", "runner_public_keys" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_installation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Configure agent installation dispatch (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.configure_agent_installation_dispatch/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_configure_agent_installation_dispatch` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.configure_agent_installation_dispatch:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_configure_agent_installation_dispatch", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "dispatch_endpoint_url": { "title": "Receiver URL signed task envelopes POST to (§6.1)", "type": "string" }, "runner_identity_ref": { "title": "Stable §8.3 identity URI presented in signed acks/results", "type": "string" }, "runner_public_keys": { "additionalProperties": true, "title": "kid → base64 Ed25519 verification keys (JSON object)", "type": "object" } }, "required": [ "dispatch_endpoint_url", "runner_public_keys" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_installation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Configure agent installation dispatch (rollup delta)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.configure_channel_connection/apply": { "post": { "description": "Re-point a conduit: endpoint, publication horizon, price basis, credential reference, partner codes, or the set of demand channels it carries. Every parameter is optional and only the ones given move — this is a patch, not a restatement. `rate_model` is deliberately absent: switching between per-day and occupancy-based pricing means re-certifying with the partner and re-publishing the whole horizon, so it is a new conduit, not an edit. Emits `channel_connection.configured`.\n\nEffects: modify hospitality.channel_connection; link hospitality.link.channel_connection_carries_channel; unlink hospitality.link.channel_connection_carries_channel.", "operationId": "apply_hospitality_action_configure_channel_connection", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "ari_endpoint_url": { "title": "HTTPS endpoint we publish ARI into", "type": "string" }, "channel_ids": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.channel" }, "title": "Demand channels this conduit carries (replaces the current set)", "type": "array" }, "display_name": { "title": "Human-readable name shown in the Explorer", "type": "string" }, "horizon_days": { "title": "Days forward from today that ARI is published for (1..=750)", "type": "integer" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "partner_code": { "title": "The partner's identifier for our system", "type": "string" }, "price_basis": { "enum": [ "gross", "net", "gross_and_net" ], "title": "Whether published amounts are gross, net, or both", "type": "string" }, "property_code": { "title": "The partner's identifier for this property", "type": "string" }, "secret_ref": { "title": "Name of the credential in the external secret store (never the value)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.channel_connection_carries_channel" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.channel_connection" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.configure_channel_connection:apply" ] } ], "summary": "Configure channel connection", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.configure_channel_connection/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_configure_channel_connection` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.configure_channel_connection:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_configure_channel_connection", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "ari_endpoint_url": { "title": "HTTPS endpoint we publish ARI into", "type": "string" }, "channel_ids": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.channel" }, "title": "Demand channels this conduit carries (replaces the current set)", "type": "array" }, "display_name": { "title": "Human-readable name shown in the Explorer", "type": "string" }, "horizon_days": { "title": "Days forward from today that ARI is published for (1..=750)", "type": "integer" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "partner_code": { "title": "The partner's identifier for our system", "type": "string" }, "price_basis": { "enum": [ "gross", "net", "gross_and_net" ], "title": "Whether published amounts are gross, net, or both", "type": "string" }, "property_code": { "title": "The partner's identifier for this property", "type": "string" }, "secret_ref": { "title": "Name of the credential in the external secret store (never the value)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.channel_connection_carries_channel" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.channel_connection" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Configure channel connection (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.configure_channel_connection/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_configure_channel_connection`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_configure_channel_connection", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "ari_endpoint_url": { "title": "HTTPS endpoint we publish ARI into", "type": "string" }, "channel_ids": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.channel" }, "title": "Demand channels this conduit carries (replaces the current set)", "type": "array" }, "display_name": { "title": "Human-readable name shown in the Explorer", "type": "string" }, "horizon_days": { "title": "Days forward from today that ARI is published for (1..=750)", "type": "integer" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "partner_code": { "title": "The partner's identifier for our system", "type": "string" }, "price_basis": { "enum": [ "gross", "net", "gross_and_net" ], "title": "Whether published amounts are gross, net, or both", "type": "string" }, "property_code": { "title": "The partner's identifier for this property", "type": "string" }, "secret_ref": { "title": "Name of the credential in the external secret store (never the value)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Configure channel connection (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.configure_channel_connection/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_configure_channel_connection` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.configure_channel_connection:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_configure_channel_connection", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "ari_endpoint_url": { "title": "HTTPS endpoint we publish ARI into", "type": "string" }, "channel_ids": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.channel" }, "title": "Demand channels this conduit carries (replaces the current set)", "type": "array" }, "display_name": { "title": "Human-readable name shown in the Explorer", "type": "string" }, "horizon_days": { "title": "Days forward from today that ARI is published for (1..=750)", "type": "integer" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "partner_code": { "title": "The partner's identifier for our system", "type": "string" }, "price_basis": { "enum": [ "gross", "net", "gross_and_net" ], "title": "Whether published amounts are gross, net, or both", "type": "string" }, "property_code": { "title": "The partner's identifier for this property", "type": "string" }, "secret_ref": { "title": "Name of the credential in the external secret store (never the value)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Configure channel connection (rollup delta)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.confirm_appointment/apply": { "post": { "description": "Mark the guest's reconfirmation on a booked appointment (Book4Time's Reminder Confirmed; Mindbody's Confirmed). Business time: `confirmed_at` defaults to now. Re-confirming a confirmed appointment is a no-op. Emits `spa.appointment_confirmed`.\n\nEffects: modify hospitality.appointment.", "operationId": "apply_hospitality_action_confirm_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "confirmed_at": { "format": "date-time", "title": "When the guest reconfirmed (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.appointment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.confirm_appointment:apply" ] } ], "summary": "Confirm appointment", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.confirm_appointment/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_confirm_appointment` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.confirm_appointment:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_confirm_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "confirmed_at": { "format": "date-time", "title": "When the guest reconfirmed (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.appointment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Confirm appointment (dry-run)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.confirm_appointment/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_confirm_appointment`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_confirm_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "confirmed_at": { "format": "date-time", "title": "When the guest reconfirmed (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Confirm appointment (dry-run)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.confirm_appointment/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_confirm_appointment` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.confirm_appointment:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_confirm_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "confirmed_at": { "format": "date-time", "title": "When the guest reconfirmed (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Confirm appointment (rollup delta)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.confirm_person_merge/apply": { "post": { "description": "Accept a pending candidate: create the `person_merged_into` link from the subordinate to the caller-chosen survivor (proposal 0027 §8.1), demote the subordinate to `resolution_status = merged_subordinate`, and reconcile the survivor's consent to the most-restrictive across the pair — a withdrawal on either row wins; a merge can never grant consent the subordinate had withdrawn (§6). Rejects self-merges, chains (either party already in a live merge), and non-active survivors. May be routed through a 0020 approval gate by operator policy (§8.2); the action itself is gate-agnostic. Emits `person.merge_confirmed`.\n\nEffects: link hospitality.link.person_merged_into; modify hospitality.person; modify hospitality.person_merge_candidate.", "operationId": "apply_hospitality_action_confirm_person_merge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "survivor_id": { "format": "uuid", "title": "Which of the candidate pair survives as the golden record", "type": "string", "x-aerandil-references": "hospitality.person" } }, "required": [ "survivor_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person_merge_candidate" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.person_merged_into" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.person", "hospitality.person_merge_candidate" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.confirm_person_merge:apply" ] } ], "summary": "Confirm person merge", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.confirm_person_merge/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_confirm_person_merge` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.confirm_person_merge:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_confirm_person_merge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "survivor_id": { "format": "uuid", "title": "Which of the candidate pair survives as the golden record", "type": "string", "x-aerandil-references": "hospitality.person" } }, "required": [ "survivor_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person_merge_candidate" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.person_merged_into" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.person", "hospitality.person_merge_candidate" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Confirm person merge (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.confirm_person_merge/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_confirm_person_merge`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_confirm_person_merge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "survivor_id": { "format": "uuid", "title": "Which of the candidate pair survives as the golden record", "type": "string", "x-aerandil-references": "hospitality.person" } }, "required": [ "survivor_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person_merge_candidate" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Confirm person merge (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.confirm_person_merge/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_confirm_person_merge` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.confirm_person_merge:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_confirm_person_merge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "survivor_id": { "format": "uuid", "title": "Which of the candidate pair survives as the golden record", "type": "string", "x-aerandil-references": "hospitality.person" } }, "required": [ "survivor_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person_merge_candidate" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Confirm person merge (rollup delta)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.consume_package_component/apply": { "post": { "description": "Record one consumption of a package component on a business date and post the corresponding charge. The reconciliation outcome (`consumed` / `profit` / `loss` / `refunded`) is derived from the consumed vs. allowance amounts.\n\nEffects: create hospitality.package_component_consumption; create hospitality.charge; modify hospitality.package_sale; link hospitality.link.package_sale_has_consumption; link hospitality.link.consumption_for_charge; link hospitality.link.folio_has_charge; link hospitality.link.charge_attributed_to_package_sale; link hospitality.link.charge_attributed_to_package_component; link hospitality.link.charge_at_outlet.", "operationId": "apply_hospitality_action_consume_package_component", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allowance_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Allowance amount", "type": "object" }, "business_date": { "format": "date", "title": "Business date", "type": "string" }, "charge_bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "USALI 12 department for the charge", "type": "string" }, "charge_description": { "title": "Charge description", "type": "string" }, "component_id": { "format": "uuid", "title": "Package component", "type": "string", "x-aerandil-references": "hospitality.package_component" }, "consumed_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Consumed amount", "type": "object" }, "folio_id": { "format": "uuid", "title": "Folio receiving the charge", "type": "string", "x-aerandil-references": "hospitality.folio" }, "outlet_id": { "format": "uuid", "title": "USALI 12 outlet the consumption charge rolls up to (proposal 0023)", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "reconciliation_kind": { "enum": [ "consumed", "profit", "loss", "refunded" ], "title": "Reconciliation outcome", "type": "string" } }, "required": [ "component_id", "folio_id", "business_date", "allowance_amount", "consumed_amount", "reconciliation_kind", "charge_description", "charge_bucket", "outlet_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.package_sale" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.package_sale_has_consumption", "hospitality.link.consumption_for_charge", "hospitality.link.folio_has_charge", "hospitality.link.charge_attributed_to_package_sale", "hospitality.link.charge_attributed_to_package_component", "hospitality.link.charge_at_outlet" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.package_component_consumption", "hospitality.charge", "hospitality.package_sale" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.consume_package_component:apply" ] } ], "summary": "Consume package component", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.consume_package_component/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_consume_package_component` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.consume_package_component:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_consume_package_component", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allowance_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Allowance amount", "type": "object" }, "business_date": { "format": "date", "title": "Business date", "type": "string" }, "charge_bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "USALI 12 department for the charge", "type": "string" }, "charge_description": { "title": "Charge description", "type": "string" }, "component_id": { "format": "uuid", "title": "Package component", "type": "string", "x-aerandil-references": "hospitality.package_component" }, "consumed_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Consumed amount", "type": "object" }, "folio_id": { "format": "uuid", "title": "Folio receiving the charge", "type": "string", "x-aerandil-references": "hospitality.folio" }, "outlet_id": { "format": "uuid", "title": "USALI 12 outlet the consumption charge rolls up to (proposal 0023)", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "reconciliation_kind": { "enum": [ "consumed", "profit", "loss", "refunded" ], "title": "Reconciliation outcome", "type": "string" } }, "required": [ "component_id", "folio_id", "business_date", "allowance_amount", "consumed_amount", "reconciliation_kind", "charge_description", "charge_bucket", "outlet_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.package_sale" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.package_sale_has_consumption", "hospitality.link.consumption_for_charge", "hospitality.link.folio_has_charge", "hospitality.link.charge_attributed_to_package_sale", "hospitality.link.charge_attributed_to_package_component", "hospitality.link.charge_at_outlet" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.package_component_consumption", "hospitality.charge", "hospitality.package_sale" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Consume package component (dry-run)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.consume_package_component/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_consume_package_component`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_consume_package_component", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allowance_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Allowance amount", "type": "object" }, "business_date": { "format": "date", "title": "Business date", "type": "string" }, "charge_bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "USALI 12 department for the charge", "type": "string" }, "charge_description": { "title": "Charge description", "type": "string" }, "component_id": { "format": "uuid", "title": "Package component", "type": "string", "x-aerandil-references": "hospitality.package_component" }, "consumed_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Consumed amount", "type": "object" }, "folio_id": { "format": "uuid", "title": "Folio receiving the charge", "type": "string", "x-aerandil-references": "hospitality.folio" }, "outlet_id": { "format": "uuid", "title": "USALI 12 outlet the consumption charge rolls up to (proposal 0023)", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "reconciliation_kind": { "enum": [ "consumed", "profit", "loss", "refunded" ], "title": "Reconciliation outcome", "type": "string" } }, "required": [ "component_id", "folio_id", "business_date", "allowance_amount", "consumed_amount", "reconciliation_kind", "charge_description", "charge_bucket", "outlet_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.package_sale" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Consume package component (dry-run)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.consume_package_component/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_consume_package_component` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.consume_package_component:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_consume_package_component", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allowance_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Allowance amount", "type": "object" }, "business_date": { "format": "date", "title": "Business date", "type": "string" }, "charge_bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "USALI 12 department for the charge", "type": "string" }, "charge_description": { "title": "Charge description", "type": "string" }, "component_id": { "format": "uuid", "title": "Package component", "type": "string", "x-aerandil-references": "hospitality.package_component" }, "consumed_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Consumed amount", "type": "object" }, "folio_id": { "format": "uuid", "title": "Folio receiving the charge", "type": "string", "x-aerandil-references": "hospitality.folio" }, "outlet_id": { "format": "uuid", "title": "USALI 12 outlet the consumption charge rolls up to (proposal 0023)", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "reconciliation_kind": { "enum": [ "consumed", "profit", "loss", "refunded" ], "title": "Reconciliation outcome", "type": "string" } }, "required": [ "component_id", "folio_id", "business_date", "allowance_amount", "consumed_amount", "reconciliation_kind", "charge_description", "charge_bucket", "outlet_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.package_sale" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Consume package component (rollup delta)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.contest_fraud_network_signal/apply": { "post": { "description": "The desk contests what Watchtower answered — the guest disputes it, and the desk believes them. The answer is marked contested with the reason, which puts the contributions behind it before the platform's review (`fraud_network.signal_contested`); the house never learns whose they are. A contested `block` lets the card rail's next answer for the same subject, within the day, take the hold to review instead of refusing it (`desk_override`). Only an answer that matched can be contested, and only once.\n\nEffects: modify hospitality.fraud_network_signal.", "operationId": "apply_hospitality_action_contest_fraud_network_signal", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the desk contests it — what the guest said, what the desk saw", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fraud_network_signal" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.fraud_network_signal" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.contest_fraud_network_signal:apply" ] } ], "summary": "Contest fraud network signal", "tags": [ "fraud_network" ] } }, "/v1/actions/hospitality.action.contest_fraud_network_signal/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_contest_fraud_network_signal` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.contest_fraud_network_signal:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_contest_fraud_network_signal", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the desk contests it — what the guest said, what the desk saw", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fraud_network_signal" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.fraud_network_signal" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Contest fraud network signal (dry-run)", "tags": [ "fraud_network" ] } }, "/v1/actions/hospitality.action.contest_fraud_network_signal/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_contest_fraud_network_signal`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_contest_fraud_network_signal", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the desk contests it — what the guest said, what the desk saw", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fraud_network_signal" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Contest fraud network signal (dry-run)", "tags": [ "fraud_network" ] } }, "/v1/actions/hospitality.action.contest_fraud_network_signal/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_contest_fraud_network_signal` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.contest_fraud_network_signal:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_contest_fraud_network_signal", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the desk contests it — what the guest said, what the desk saw", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fraud_network_signal" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Contest fraud network signal (rollup delta)", "tags": [ "fraud_network" ] } }, "/v1/actions/hospitality.action.convert_group_request_to_reservation/apply": { "post": { "description": "Attach a reservation to a group_request, marking the group request as `confirmed`. Multi-property and multi-room blocks invoke this once per reservation; the action is idempotent on the (group_request, reservation) pair.\n\nEffects: modify hospitality.group_request; link hospitality.link.group_request_converts_to_reservation.", "operationId": "apply_hospitality_action_convert_group_request_to_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reservation_id": { "format": "uuid", "title": "Reservation to attach", "type": "string", "x-aerandil-references": "hospitality.reservation" } }, "required": [ "reservation_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_request" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.group_request_converts_to_reservation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.group_request" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.convert_group_request_to_reservation:apply" ] } ], "summary": "Convert group request to reservation", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.convert_group_request_to_reservation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_convert_group_request_to_reservation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.convert_group_request_to_reservation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_convert_group_request_to_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reservation_id": { "format": "uuid", "title": "Reservation to attach", "type": "string", "x-aerandil-references": "hospitality.reservation" } }, "required": [ "reservation_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_request" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.group_request_converts_to_reservation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.group_request" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Convert group request to reservation (dry-run)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.convert_group_request_to_reservation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_convert_group_request_to_reservation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_convert_group_request_to_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reservation_id": { "format": "uuid", "title": "Reservation to attach", "type": "string", "x-aerandil-references": "hospitality.reservation" } }, "required": [ "reservation_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_request" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Convert group request to reservation (dry-run)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.convert_group_request_to_reservation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_convert_group_request_to_reservation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.convert_group_request_to_reservation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_convert_group_request_to_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reservation_id": { "format": "uuid", "title": "Reservation to attach", "type": "string", "x-aerandil-references": "hospitality.reservation" } }, "required": [ "reservation_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_request" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Convert group request to reservation (rollup delta)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.create_function_space/apply": { "post": { "description": "Add a bookable function room to the property's diary. `capacities` is a JSON array of `{setup_style, capacity}` rows; a `combined_space_id` makes the new room a section of a divisible one. The code must be unique at the property.\n\nEffects: create hospitality.function_space; link hospitality.link.function_space_at_property; link hospitality.link.function_space_section_of.", "operationId": "apply_hospitality_action_create_function_space", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "area_sqm": { "format": "decimal", "title": "Floor area in square metres", "type": "string" }, "capacities": { "title": "Capacity per setup style: [{setup_style, capacity}]" }, "code": { "title": "Operator-facing code", "type": "string" }, "combined_space_id": { "format": "uuid", "title": "The divisible room this space is a section of", "type": "string", "x-aerandil-references": "hospitality.function_space" }, "divisible": { "title": "Whether the room splits into sections (default false)", "type": "boolean" }, "location": { "title": "Where in the house", "type": "string" }, "name": { "title": "Display name", "type": "string" }, "notes": { "title": "Operational notes", "type": "string" } }, "required": [ "code", "name", "capacities" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.function_space_at_property", "hospitality.link.function_space_section_of" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.function_space" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.create_function_space:apply" ] } ], "summary": "Create function space", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.create_function_space/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_create_function_space` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.create_function_space:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_create_function_space", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "area_sqm": { "format": "decimal", "title": "Floor area in square metres", "type": "string" }, "capacities": { "title": "Capacity per setup style: [{setup_style, capacity}]" }, "code": { "title": "Operator-facing code", "type": "string" }, "combined_space_id": { "format": "uuid", "title": "The divisible room this space is a section of", "type": "string", "x-aerandil-references": "hospitality.function_space" }, "divisible": { "title": "Whether the room splits into sections (default false)", "type": "boolean" }, "location": { "title": "Where in the house", "type": "string" }, "name": { "title": "Display name", "type": "string" }, "notes": { "title": "Operational notes", "type": "string" } }, "required": [ "code", "name", "capacities" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.function_space_at_property", "hospitality.link.function_space_section_of" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.function_space" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Create function space (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.create_function_space/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_create_function_space`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_create_function_space", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "area_sqm": { "format": "decimal", "title": "Floor area in square metres", "type": "string" }, "capacities": { "title": "Capacity per setup style: [{setup_style, capacity}]" }, "code": { "title": "Operator-facing code", "type": "string" }, "combined_space_id": { "format": "uuid", "title": "The divisible room this space is a section of", "type": "string", "x-aerandil-references": "hospitality.function_space" }, "divisible": { "title": "Whether the room splits into sections (default false)", "type": "boolean" }, "location": { "title": "Where in the house", "type": "string" }, "name": { "title": "Display name", "type": "string" }, "notes": { "title": "Operational notes", "type": "string" } }, "required": [ "code", "name", "capacities" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Create function space (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.create_function_space/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_create_function_space` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.create_function_space:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_create_function_space", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "area_sqm": { "format": "decimal", "title": "Floor area in square metres", "type": "string" }, "capacities": { "title": "Capacity per setup style: [{setup_style, capacity}]" }, "code": { "title": "Operator-facing code", "type": "string" }, "combined_space_id": { "format": "uuid", "title": "The divisible room this space is a section of", "type": "string", "x-aerandil-references": "hospitality.function_space" }, "divisible": { "title": "Whether the room splits into sections (default false)", "type": "boolean" }, "location": { "title": "Where in the house", "type": "string" }, "name": { "title": "Display name", "type": "string" }, "notes": { "title": "Operational notes", "type": "string" } }, "required": [ "code", "name", "capacities" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Create function space (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.create_group_block/apply": { "post": { "description": "Open an operational room block at this property. The block starts `tentative` — it holds no inventory until it is made `definite`. Optionally attaches to the group_request it came from; blocks with no request behind them are legitimate.\n\nEffects: create hospitality.group_block; link hospitality.link.block_for_property; link hospitality.link.group_request_has_block.", "operationId": "apply_hospitality_action_create_group_block", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancel_returns_to": { "enum": [ "house", "block" ], "title": "Where a cancelled pickup's room goes (default house)", "type": "string" }, "code": { "title": "Operator-facing block code", "type": "string" }, "cutoff_date": { "format": "date", "title": "Cutoff date (required when cutoff_mode = fixed)", "type": "string" }, "cutoff_days": { "title": "Days before each stay night (required when cutoff_mode = rolling)", "type": "integer" }, "cutoff_mode": { "enum": [ "none", "fixed", "rolling" ], "title": "Cutoff mode", "type": "string" }, "end_date": { "format": "date", "title": "Departure date (exclusive of the last stay night)", "type": "string" }, "group_request_id": { "format": "uuid", "title": "The group request this block came from", "type": "string", "x-aerandil-references": "hospitality.group_request" }, "name": { "title": "Block name", "type": "string" }, "rate_plan_id": { "format": "uuid", "title": "Block-private rate plan", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "rooming_list_due": { "format": "date", "title": "Date the group owes its rooming list", "type": "string" }, "start_date": { "format": "date", "title": "First stay night", "type": "string" } }, "required": [ "name", "start_date", "end_date", "cutoff_mode" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.block_for_property", "hospitality.link.group_request_has_block" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.group_block" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.create_group_block:apply" ] } ], "summary": "Create group block", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.create_group_block/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_create_group_block` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.create_group_block:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_create_group_block", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancel_returns_to": { "enum": [ "house", "block" ], "title": "Where a cancelled pickup's room goes (default house)", "type": "string" }, "code": { "title": "Operator-facing block code", "type": "string" }, "cutoff_date": { "format": "date", "title": "Cutoff date (required when cutoff_mode = fixed)", "type": "string" }, "cutoff_days": { "title": "Days before each stay night (required when cutoff_mode = rolling)", "type": "integer" }, "cutoff_mode": { "enum": [ "none", "fixed", "rolling" ], "title": "Cutoff mode", "type": "string" }, "end_date": { "format": "date", "title": "Departure date (exclusive of the last stay night)", "type": "string" }, "group_request_id": { "format": "uuid", "title": "The group request this block came from", "type": "string", "x-aerandil-references": "hospitality.group_request" }, "name": { "title": "Block name", "type": "string" }, "rate_plan_id": { "format": "uuid", "title": "Block-private rate plan", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "rooming_list_due": { "format": "date", "title": "Date the group owes its rooming list", "type": "string" }, "start_date": { "format": "date", "title": "First stay night", "type": "string" } }, "required": [ "name", "start_date", "end_date", "cutoff_mode" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.block_for_property", "hospitality.link.group_request_has_block" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.group_block" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Create group block (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.create_group_block/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_create_group_block`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_create_group_block", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancel_returns_to": { "enum": [ "house", "block" ], "title": "Where a cancelled pickup's room goes (default house)", "type": "string" }, "code": { "title": "Operator-facing block code", "type": "string" }, "cutoff_date": { "format": "date", "title": "Cutoff date (required when cutoff_mode = fixed)", "type": "string" }, "cutoff_days": { "title": "Days before each stay night (required when cutoff_mode = rolling)", "type": "integer" }, "cutoff_mode": { "enum": [ "none", "fixed", "rolling" ], "title": "Cutoff mode", "type": "string" }, "end_date": { "format": "date", "title": "Departure date (exclusive of the last stay night)", "type": "string" }, "group_request_id": { "format": "uuid", "title": "The group request this block came from", "type": "string", "x-aerandil-references": "hospitality.group_request" }, "name": { "title": "Block name", "type": "string" }, "rate_plan_id": { "format": "uuid", "title": "Block-private rate plan", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "rooming_list_due": { "format": "date", "title": "Date the group owes its rooming list", "type": "string" }, "start_date": { "format": "date", "title": "First stay night", "type": "string" } }, "required": [ "name", "start_date", "end_date", "cutoff_mode" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Create group block (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.create_group_block/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_create_group_block` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.create_group_block:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_create_group_block", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cancel_returns_to": { "enum": [ "house", "block" ], "title": "Where a cancelled pickup's room goes (default house)", "type": "string" }, "code": { "title": "Operator-facing block code", "type": "string" }, "cutoff_date": { "format": "date", "title": "Cutoff date (required when cutoff_mode = fixed)", "type": "string" }, "cutoff_days": { "title": "Days before each stay night (required when cutoff_mode = rolling)", "type": "integer" }, "cutoff_mode": { "enum": [ "none", "fixed", "rolling" ], "title": "Cutoff mode", "type": "string" }, "end_date": { "format": "date", "title": "Departure date (exclusive of the last stay night)", "type": "string" }, "group_request_id": { "format": "uuid", "title": "The group request this block came from", "type": "string", "x-aerandil-references": "hospitality.group_request" }, "name": { "title": "Block name", "type": "string" }, "rate_plan_id": { "format": "uuid", "title": "Block-private rate plan", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "rooming_list_due": { "format": "date", "title": "Date the group owes its rooming list", "type": "string" }, "start_date": { "format": "date", "title": "First stay night", "type": "string" } }, "required": [ "name", "start_date", "end_date", "cutoff_mode" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Create group block (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.create_housekeeping_task/apply": { "post": { "description": "Mint an ad-hoc housekeeping task against a room — a deep clean, an inspection, a guest-requested refresh. Carries no generation_key, so the generator's convergence sweep never touches it. Refuses a room under an active out-of-order block covering the service date (release decides the state the room re-enters in). `credits` and `standard_minutes` come from the property's most specific active housekeeping credit rule for the task type and the room's type, unless given here. `assignee_id` assigns it in the same write (a staff member at the room's house), so an inspection a supervisor starts is theirs from the first moment rather than on every attendant's open list; a housekeeper or runner session may name only itself — giving work to someone else is the supervisor's assign_housekeeping_task. Stamps `origin` manual (from_triage when from_triage_id is given). A room takes a room's task types only; a public area's work is create_public_area_task's (2026-10-14). A task is a request (2026-10-15): `requested_by` says who asked — when unstated, guest for a named `stay_id` (linked, `housekeeping_task_requested_by_stay`) or `from_triage_id`, else the caller's side: floor for a housekeeper's, runner's, supervisor's or engineer's handset, desk for any other person, automation for an agent or a service. A floor session states only floor — a guest's request is the desk's or triage's to record (403). `due_at` is when it is due, no earlier than the start of the day before the house's hotel date; with no `business_date` the task belongs to its due time's day. Its urgency is the housekeeping_requests read's.\n\nEffects: create hospitality.housekeeping_task; link hospitality.link.housekeeping_task_for_room; link hospitality.link.housekeeping_task_requested_by_stay; link hospitality.link.housekeeping_task_from_triage; link hospitality.link.housekeeping_task_assigned_to; link hospitality.link.housekeeping_task_for_area.", "operationId": "apply_hospitality_action_create_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "assignee_id": { "format": "uuid", "title": "Staff member to assign the task to in the same write — someone at the room's house; a housekeeper or runner session names only itself", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "business_date": { "format": "date", "title": "Service date (defaults to the property-local business day)", "type": "string" }, "credits": { "format": "decimal", "title": "Credits the task is worth, overriding the house's credit rule (zero or more)", "type": "string" }, "due_at": { "format": "date-time", "title": "When the work is due (no earlier than the start of the day before the house's today)", "type": "string" }, "from_triage_id": { "format": "uuid", "title": "The triaged guest request that asked for this, if one did — links the task back to the conversation so the lane closing the loop knows where to reply", "type": "string", "x-aerandil-references": "hospitality.message_triage" }, "notes": { "title": "Notes for the attendant", "type": "string" }, "priority": { "enum": [ "low", "normal", "high", "urgent" ], "title": "Priority (defaults to normal)", "type": "string" }, "requested_by": { "enum": [ "guest", "desk", "floor", "pms", "automation" ], "title": "Who asked: guest, desk, floor, pms or automation (defaults from the caller — guest when stay_id or from_triage_id is named)", "type": "string" }, "standard_minutes": { "title": "Minutes the work should take, overriding the house's credit rule (1 to 1440)", "type": "integer" }, "stay_id": { "format": "uuid", "title": "The guest stay that asked for the work — a stay at the task's house", "type": "string", "x-aerandil-references": "hospitality.stay" }, "task_type": { "enum": [ "stayover", "departure", "vacant_pickup", "deep_clean", "turndown", "inspection", "public_area_clean", "public_area_inspection", "minibar", "laundry" ], "title": "Kind of work", "type": "string" } }, "required": [ "task_type" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.housekeeping_task_for_room", "hospitality.link.housekeeping_task_requested_by_stay", "hospitality.link.housekeeping_task_from_triage", "hospitality.link.housekeeping_task_assigned_to", "hospitality.link.housekeeping_task_for_area" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.create_housekeeping_task:apply" ] } ], "summary": "Create housekeeping task", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.create_housekeeping_task/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_create_housekeeping_task` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.create_housekeeping_task:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_create_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "assignee_id": { "format": "uuid", "title": "Staff member to assign the task to in the same write — someone at the room's house; a housekeeper or runner session names only itself", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "business_date": { "format": "date", "title": "Service date (defaults to the property-local business day)", "type": "string" }, "credits": { "format": "decimal", "title": "Credits the task is worth, overriding the house's credit rule (zero or more)", "type": "string" }, "due_at": { "format": "date-time", "title": "When the work is due (no earlier than the start of the day before the house's today)", "type": "string" }, "from_triage_id": { "format": "uuid", "title": "The triaged guest request that asked for this, if one did — links the task back to the conversation so the lane closing the loop knows where to reply", "type": "string", "x-aerandil-references": "hospitality.message_triage" }, "notes": { "title": "Notes for the attendant", "type": "string" }, "priority": { "enum": [ "low", "normal", "high", "urgent" ], "title": "Priority (defaults to normal)", "type": "string" }, "requested_by": { "enum": [ "guest", "desk", "floor", "pms", "automation" ], "title": "Who asked: guest, desk, floor, pms or automation (defaults from the caller — guest when stay_id or from_triage_id is named)", "type": "string" }, "standard_minutes": { "title": "Minutes the work should take, overriding the house's credit rule (1 to 1440)", "type": "integer" }, "stay_id": { "format": "uuid", "title": "The guest stay that asked for the work — a stay at the task's house", "type": "string", "x-aerandil-references": "hospitality.stay" }, "task_type": { "enum": [ "stayover", "departure", "vacant_pickup", "deep_clean", "turndown", "inspection", "public_area_clean", "public_area_inspection", "minibar", "laundry" ], "title": "Kind of work", "type": "string" } }, "required": [ "task_type" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.housekeeping_task_for_room", "hospitality.link.housekeeping_task_requested_by_stay", "hospitality.link.housekeeping_task_from_triage", "hospitality.link.housekeeping_task_assigned_to", "hospitality.link.housekeeping_task_for_area" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Create housekeeping task (dry-run)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.create_housekeeping_task/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_create_housekeeping_task`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_create_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "assignee_id": { "format": "uuid", "title": "Staff member to assign the task to in the same write — someone at the room's house; a housekeeper or runner session names only itself", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "business_date": { "format": "date", "title": "Service date (defaults to the property-local business day)", "type": "string" }, "credits": { "format": "decimal", "title": "Credits the task is worth, overriding the house's credit rule (zero or more)", "type": "string" }, "due_at": { "format": "date-time", "title": "When the work is due (no earlier than the start of the day before the house's today)", "type": "string" }, "from_triage_id": { "format": "uuid", "title": "The triaged guest request that asked for this, if one did — links the task back to the conversation so the lane closing the loop knows where to reply", "type": "string", "x-aerandil-references": "hospitality.message_triage" }, "notes": { "title": "Notes for the attendant", "type": "string" }, "priority": { "enum": [ "low", "normal", "high", "urgent" ], "title": "Priority (defaults to normal)", "type": "string" }, "requested_by": { "enum": [ "guest", "desk", "floor", "pms", "automation" ], "title": "Who asked: guest, desk, floor, pms or automation (defaults from the caller — guest when stay_id or from_triage_id is named)", "type": "string" }, "standard_minutes": { "title": "Minutes the work should take, overriding the house's credit rule (1 to 1440)", "type": "integer" }, "stay_id": { "format": "uuid", "title": "The guest stay that asked for the work — a stay at the task's house", "type": "string", "x-aerandil-references": "hospitality.stay" }, "task_type": { "enum": [ "stayover", "departure", "vacant_pickup", "deep_clean", "turndown", "inspection", "public_area_clean", "public_area_inspection", "minibar", "laundry" ], "title": "Kind of work", "type": "string" } }, "required": [ "task_type" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Create housekeeping task (dry-run)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.create_housekeeping_task/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_create_housekeeping_task` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.create_housekeeping_task:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_create_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "assignee_id": { "format": "uuid", "title": "Staff member to assign the task to in the same write — someone at the room's house; a housekeeper or runner session names only itself", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "business_date": { "format": "date", "title": "Service date (defaults to the property-local business day)", "type": "string" }, "credits": { "format": "decimal", "title": "Credits the task is worth, overriding the house's credit rule (zero or more)", "type": "string" }, "due_at": { "format": "date-time", "title": "When the work is due (no earlier than the start of the day before the house's today)", "type": "string" }, "from_triage_id": { "format": "uuid", "title": "The triaged guest request that asked for this, if one did — links the task back to the conversation so the lane closing the loop knows where to reply", "type": "string", "x-aerandil-references": "hospitality.message_triage" }, "notes": { "title": "Notes for the attendant", "type": "string" }, "priority": { "enum": [ "low", "normal", "high", "urgent" ], "title": "Priority (defaults to normal)", "type": "string" }, "requested_by": { "enum": [ "guest", "desk", "floor", "pms", "automation" ], "title": "Who asked: guest, desk, floor, pms or automation (defaults from the caller — guest when stay_id or from_triage_id is named)", "type": "string" }, "standard_minutes": { "title": "Minutes the work should take, overriding the house's credit rule (1 to 1440)", "type": "integer" }, "stay_id": { "format": "uuid", "title": "The guest stay that asked for the work — a stay at the task's house", "type": "string", "x-aerandil-references": "hospitality.stay" }, "task_type": { "enum": [ "stayover", "departure", "vacant_pickup", "deep_clean", "turndown", "inspection", "public_area_clean", "public_area_inspection", "minibar", "laundry" ], "title": "Kind of work", "type": "string" } }, "required": [ "task_type" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Create housekeeping task (rollup delta)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.create_public_area_task/apply": { "post": { "description": "Mint an ad-hoc housekeeping task for a public area — the clean a scan of its code opens on the handset, an extra round of the lobby toilets, or the supervisor's inspection of the area — through `create_housekeeping_task`'s own path, linked `housekeeping_task_for_area` instead of to a room. `task_type` is `public_area_clean` (the default) or `public_area_inspection`. Carries no generation_key, so the generator never touches it; `credits` and `standard_minutes` come from the house's credit rule for the task type unless given; `assignee_id` assigns it in the same write (a housekeeper or runner session names only itself). Refuses a retired area. The area's checklist resolves by its kind (`checklist_for_task`), and an inspection's verdict at completion rates the area's latest completed clean that day, as a room's does. Stamps `origin` manual and the task's own `area_id`; emits `housekeeping.task.created` with `area_id`. `requested_by`, `stay_id` and `due_at` (2026-10-15) are create_housekeeping_task's — a floor session states only floor, and a guest's request is the desk's or triage's.\n\nEffects: create hospitality.housekeeping_task; link hospitality.link.housekeeping_task_requested_by_stay; link hospitality.link.housekeeping_task_for_area; link hospitality.link.housekeeping_task_for_room; link hospitality.link.housekeeping_task_from_triage; link hospitality.link.housekeeping_task_assigned_to.", "operationId": "apply_hospitality_action_create_public_area_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "assignee_id": { "format": "uuid", "title": "Staff member to assign the task to in the same write — someone at the area's house; a housekeeper or runner session names only itself", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "business_date": { "format": "date", "title": "Service date (defaults to the property-local business day)", "type": "string" }, "credits": { "format": "decimal", "title": "Credits the task is worth, overriding the house's credit rule (zero or more)", "type": "string" }, "due_at": { "format": "date-time", "title": "When the work is due (no earlier than the start of the day before the house's today)", "type": "string" }, "notes": { "title": "Notes for the attendant", "type": "string" }, "priority": { "enum": [ "low", "normal", "high", "urgent" ], "title": "Priority (defaults to normal)", "type": "string" }, "requested_by": { "enum": [ "guest", "desk", "floor", "pms", "automation" ], "title": "Who asked: guest, desk, floor, pms or automation (defaults from the caller — guest when stay_id is named)", "type": "string" }, "standard_minutes": { "title": "Minutes the work should take, overriding the house's credit rule (1 to 1440)", "type": "integer" }, "stay_id": { "format": "uuid", "title": "The guest stay that asked for the work — a stay at the area's house", "type": "string", "x-aerandil-references": "hospitality.stay" }, "task_type": { "enum": [ "public_area_clean", "public_area_inspection" ], "title": "public_area_clean (the default) or public_area_inspection", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.public_area" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.housekeeping_task_requested_by_stay", "hospitality.link.housekeeping_task_for_area", "hospitality.link.housekeeping_task_for_room", "hospitality.link.housekeeping_task_from_triage", "hospitality.link.housekeeping_task_assigned_to" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.create_public_area_task:apply" ] } ], "summary": "Create public area task", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.create_public_area_task/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_create_public_area_task` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.create_public_area_task:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_create_public_area_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "assignee_id": { "format": "uuid", "title": "Staff member to assign the task to in the same write — someone at the area's house; a housekeeper or runner session names only itself", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "business_date": { "format": "date", "title": "Service date (defaults to the property-local business day)", "type": "string" }, "credits": { "format": "decimal", "title": "Credits the task is worth, overriding the house's credit rule (zero or more)", "type": "string" }, "due_at": { "format": "date-time", "title": "When the work is due (no earlier than the start of the day before the house's today)", "type": "string" }, "notes": { "title": "Notes for the attendant", "type": "string" }, "priority": { "enum": [ "low", "normal", "high", "urgent" ], "title": "Priority (defaults to normal)", "type": "string" }, "requested_by": { "enum": [ "guest", "desk", "floor", "pms", "automation" ], "title": "Who asked: guest, desk, floor, pms or automation (defaults from the caller — guest when stay_id is named)", "type": "string" }, "standard_minutes": { "title": "Minutes the work should take, overriding the house's credit rule (1 to 1440)", "type": "integer" }, "stay_id": { "format": "uuid", "title": "The guest stay that asked for the work — a stay at the area's house", "type": "string", "x-aerandil-references": "hospitality.stay" }, "task_type": { "enum": [ "public_area_clean", "public_area_inspection" ], "title": "public_area_clean (the default) or public_area_inspection", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.public_area" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.housekeeping_task_requested_by_stay", "hospitality.link.housekeeping_task_for_area", "hospitality.link.housekeeping_task_for_room", "hospitality.link.housekeeping_task_from_triage", "hospitality.link.housekeeping_task_assigned_to" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Create public area task (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.create_public_area_task/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_create_public_area_task`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_create_public_area_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "assignee_id": { "format": "uuid", "title": "Staff member to assign the task to in the same write — someone at the area's house; a housekeeper or runner session names only itself", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "business_date": { "format": "date", "title": "Service date (defaults to the property-local business day)", "type": "string" }, "credits": { "format": "decimal", "title": "Credits the task is worth, overriding the house's credit rule (zero or more)", "type": "string" }, "due_at": { "format": "date-time", "title": "When the work is due (no earlier than the start of the day before the house's today)", "type": "string" }, "notes": { "title": "Notes for the attendant", "type": "string" }, "priority": { "enum": [ "low", "normal", "high", "urgent" ], "title": "Priority (defaults to normal)", "type": "string" }, "requested_by": { "enum": [ "guest", "desk", "floor", "pms", "automation" ], "title": "Who asked: guest, desk, floor, pms or automation (defaults from the caller — guest when stay_id is named)", "type": "string" }, "standard_minutes": { "title": "Minutes the work should take, overriding the house's credit rule (1 to 1440)", "type": "integer" }, "stay_id": { "format": "uuid", "title": "The guest stay that asked for the work — a stay at the area's house", "type": "string", "x-aerandil-references": "hospitality.stay" }, "task_type": { "enum": [ "public_area_clean", "public_area_inspection" ], "title": "public_area_clean (the default) or public_area_inspection", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.public_area" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Create public area task (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.create_public_area_task/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_create_public_area_task` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.create_public_area_task:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_create_public_area_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "assignee_id": { "format": "uuid", "title": "Staff member to assign the task to in the same write — someone at the area's house; a housekeeper or runner session names only itself", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "business_date": { "format": "date", "title": "Service date (defaults to the property-local business day)", "type": "string" }, "credits": { "format": "decimal", "title": "Credits the task is worth, overriding the house's credit rule (zero or more)", "type": "string" }, "due_at": { "format": "date-time", "title": "When the work is due (no earlier than the start of the day before the house's today)", "type": "string" }, "notes": { "title": "Notes for the attendant", "type": "string" }, "priority": { "enum": [ "low", "normal", "high", "urgent" ], "title": "Priority (defaults to normal)", "type": "string" }, "requested_by": { "enum": [ "guest", "desk", "floor", "pms", "automation" ], "title": "Who asked: guest, desk, floor, pms or automation (defaults from the caller — guest when stay_id is named)", "type": "string" }, "standard_minutes": { "title": "Minutes the work should take, overriding the house's credit rule (1 to 1440)", "type": "integer" }, "stay_id": { "format": "uuid", "title": "The guest stay that asked for the work — a stay at the area's house", "type": "string", "x-aerandil-references": "hospitality.stay" }, "task_type": { "enum": [ "public_area_clean", "public_area_inspection" ], "title": "public_area_clean (the default) or public_area_inspection", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.public_area" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Create public area task (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.create_public_area_work_order/apply": { "post": { "description": "Raise a maintenance work order against a public area — the lobby's blown light, the lift that sticks, the pool's broken tile — through `create_work_order`'s own path, linked `work_order_for_area` instead of to a room (an order is for one place). Takes create_work_order's words: `title`, `category`, `severity` (each filled from `fault_type_id` when not stated; the category from the `element` when neither names one), `description`, `staff_member_id`, `asset_id`, `stay_id`, `from_triage_id`. An area is not inventory, so there is no out-of-order window. Refuses a retired area. An order already open at the area under the same title or fault type is that order: nothing is minted, the response carries a `work-order-open-twin` warning naming it and `work_order.reported_again` records the report — unless `allow_duplicate`; a `staff_member_id` the call names takes the twin when nobody holds it (2026-10-17), and a holder it already has keeps it. Postpone, resume, the thread, assignment and completion serve it unchanged. Emits `work_order.created` with `area_id`.\n\nEffects: create hospitality.work_order; link hospitality.link.work_order_for_area; link hospitality.link.work_order_of_fault_type; link hospitality.link.work_order_from_triage; link hospitality.link.work_order_for_room; link hospitality.link.work_order_assigned_to; create hospitality.room_status_block; link hospitality.link.room_status_block_for_room; link hospitality.link.work_order_holds_block; modify hospitality.availability_day; link hospitality.link.work_order_for_asset; link hospitality.link.work_order_reported_by_stay; modify hospitality.work_order.", "operationId": "apply_hospitality_action_create_public_area_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allow_duplicate": { "title": "Raise it even when an order with the same title or fault type is already open at the area", "type": "boolean" }, "asset_id": { "format": "uuid", "title": "The equipment that failed, when the order is for one — same house, not retired", "type": "string", "x-aerandil-references": "hospitality.asset" }, "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "Category (defaults to the fault type's, else the element's trade)", "type": "string" }, "description": { "title": "Description", "type": "string" }, "element": { "enum": [ "light", "air_conditioning", "curtain", "safe", "door", "television", "phone", "wardrobe", "shower", "mirror", "toilet", "pipework", "minibar", "electrical", "other" ], "title": "The element the fault is in (defaults to the fault type's)", "type": "string" }, "fault_type_id": { "format": "uuid", "title": "The catalogue entry the fault is — the house's or its brand's, active", "type": "string", "x-aerandil-references": "hospitality.fault_type" }, "from_triage_id": { "format": "uuid", "title": "The triaged guest report that raised this, if one did", "type": "string", "x-aerandil-references": "hospitality.message_triage" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "title": "Severity (defaults to the fault type's)", "type": "string" }, "staff_member_id": { "format": "uuid", "title": "Engineer to assign on creation", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "stay_id": { "format": "uuid", "title": "The guest stay that reported the fault", "type": "string", "x-aerandil-references": "hospitality.stay" }, "title": { "title": "Title (defaults to the fault type's, else the element's name)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.public_area" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.work_order_for_area", "hospitality.link.work_order_of_fault_type", "hospitality.link.work_order_from_triage", "hospitality.link.work_order_for_room", "hospitality.link.work_order_assigned_to", "hospitality.link.room_status_block_for_room", "hospitality.link.work_order_holds_block", "hospitality.link.work_order_for_asset", "hospitality.link.work_order_reported_by_stay" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.work_order", "hospitality.room_status_block", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.create_public_area_work_order:apply" ] } ], "summary": "Create public area work order", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.create_public_area_work_order/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_create_public_area_work_order` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.create_public_area_work_order:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_create_public_area_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allow_duplicate": { "title": "Raise it even when an order with the same title or fault type is already open at the area", "type": "boolean" }, "asset_id": { "format": "uuid", "title": "The equipment that failed, when the order is for one — same house, not retired", "type": "string", "x-aerandil-references": "hospitality.asset" }, "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "Category (defaults to the fault type's, else the element's trade)", "type": "string" }, "description": { "title": "Description", "type": "string" }, "element": { "enum": [ "light", "air_conditioning", "curtain", "safe", "door", "television", "phone", "wardrobe", "shower", "mirror", "toilet", "pipework", "minibar", "electrical", "other" ], "title": "The element the fault is in (defaults to the fault type's)", "type": "string" }, "fault_type_id": { "format": "uuid", "title": "The catalogue entry the fault is — the house's or its brand's, active", "type": "string", "x-aerandil-references": "hospitality.fault_type" }, "from_triage_id": { "format": "uuid", "title": "The triaged guest report that raised this, if one did", "type": "string", "x-aerandil-references": "hospitality.message_triage" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "title": "Severity (defaults to the fault type's)", "type": "string" }, "staff_member_id": { "format": "uuid", "title": "Engineer to assign on creation", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "stay_id": { "format": "uuid", "title": "The guest stay that reported the fault", "type": "string", "x-aerandil-references": "hospitality.stay" }, "title": { "title": "Title (defaults to the fault type's, else the element's name)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.public_area" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.work_order_for_area", "hospitality.link.work_order_of_fault_type", "hospitality.link.work_order_from_triage", "hospitality.link.work_order_for_room", "hospitality.link.work_order_assigned_to", "hospitality.link.room_status_block_for_room", "hospitality.link.work_order_holds_block", "hospitality.link.work_order_for_asset", "hospitality.link.work_order_reported_by_stay" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.work_order", "hospitality.room_status_block", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Create public area work order (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.create_public_area_work_order/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_create_public_area_work_order`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_create_public_area_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allow_duplicate": { "title": "Raise it even when an order with the same title or fault type is already open at the area", "type": "boolean" }, "asset_id": { "format": "uuid", "title": "The equipment that failed, when the order is for one — same house, not retired", "type": "string", "x-aerandil-references": "hospitality.asset" }, "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "Category (defaults to the fault type's, else the element's trade)", "type": "string" }, "description": { "title": "Description", "type": "string" }, "element": { "enum": [ "light", "air_conditioning", "curtain", "safe", "door", "television", "phone", "wardrobe", "shower", "mirror", "toilet", "pipework", "minibar", "electrical", "other" ], "title": "The element the fault is in (defaults to the fault type's)", "type": "string" }, "fault_type_id": { "format": "uuid", "title": "The catalogue entry the fault is — the house's or its brand's, active", "type": "string", "x-aerandil-references": "hospitality.fault_type" }, "from_triage_id": { "format": "uuid", "title": "The triaged guest report that raised this, if one did", "type": "string", "x-aerandil-references": "hospitality.message_triage" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "title": "Severity (defaults to the fault type's)", "type": "string" }, "staff_member_id": { "format": "uuid", "title": "Engineer to assign on creation", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "stay_id": { "format": "uuid", "title": "The guest stay that reported the fault", "type": "string", "x-aerandil-references": "hospitality.stay" }, "title": { "title": "Title (defaults to the fault type's, else the element's name)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.public_area" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Create public area work order (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.create_public_area_work_order/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_create_public_area_work_order` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.create_public_area_work_order:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_create_public_area_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allow_duplicate": { "title": "Raise it even when an order with the same title or fault type is already open at the area", "type": "boolean" }, "asset_id": { "format": "uuid", "title": "The equipment that failed, when the order is for one — same house, not retired", "type": "string", "x-aerandil-references": "hospitality.asset" }, "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "Category (defaults to the fault type's, else the element's trade)", "type": "string" }, "description": { "title": "Description", "type": "string" }, "element": { "enum": [ "light", "air_conditioning", "curtain", "safe", "door", "television", "phone", "wardrobe", "shower", "mirror", "toilet", "pipework", "minibar", "electrical", "other" ], "title": "The element the fault is in (defaults to the fault type's)", "type": "string" }, "fault_type_id": { "format": "uuid", "title": "The catalogue entry the fault is — the house's or its brand's, active", "type": "string", "x-aerandil-references": "hospitality.fault_type" }, "from_triage_id": { "format": "uuid", "title": "The triaged guest report that raised this, if one did", "type": "string", "x-aerandil-references": "hospitality.message_triage" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "title": "Severity (defaults to the fault type's)", "type": "string" }, "staff_member_id": { "format": "uuid", "title": "Engineer to assign on creation", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "stay_id": { "format": "uuid", "title": "The guest stay that reported the fault", "type": "string", "x-aerandil-references": "hospitality.stay" }, "title": { "title": "Title (defaults to the fault type's, else the element's name)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.public_area" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Create public area work order (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.create_reservation/apply": { "post": { "description": "Open a new reservation against a property and rate plan. Single-room bookings pass room_type_id / adults / children / nightly_rate at top level; multi-room bookings pass one `rooms` entry per room instead (the handler rejects mixing the two shapes). A room's nightly_rate is optional: passed, it books on every night; omitted, the room is priced night by night off the published rate_per_night grid for (property, rate plan, room type, adults) and a night with no published rate refuses by date. Reservation-level adults / children are the totals across rooms; the reservation-level room_type link is written only when every room shares one type — per-room truth always lives on reservation_room_for_room_type.\n\nEffects: create hospitality.reservation; create hospitality.reservation_room; create hospitality.reservation_night; link hospitality.link.reservation_for_property; link hospitality.link.reservation_for_guest; link hospitality.link.reservation_uses_rate_plan; link hospitality.link.reservation_uses_cancellation_policy; link hospitality.link.reservation_for_room_type; link hospitality.link.reservation_has_room; link hospitality.link.reservation_room_for_room_type; link hospitality.link.reservation_room_has_night; link hospitality.link.reservation_night_uses_rate_plan; link hospitality.link.reservation_booked_in_session; modify hospitality.availability_day.", "operationId": "apply_hospitality_action_create_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults": { "title": "Adults (single-room shape; required unless `rooms` is passed)", "type": "integer" }, "arrival_date": { "format": "date", "title": "Arrival", "type": "string" }, "booked_at": { "format": "date-time", "title": "Booking instant (defaults to now; must not be in the future or after arrival)", "type": "string" }, "channel_reference": { "title": "External channel reference (OTA confirmation / GDS locator)", "type": "string" }, "children": { "title": "Children (single-room shape; required unless `rooms` is passed)", "type": "integer" }, "confirmation_number": { "title": "Source-system confirmation number (connector loads only; defaults to a minted R-…)", "type": "string" }, "departure_date": { "format": "date", "title": "Departure", "type": "string" }, "deposit_due_at": { "format": "date-time", "title": "Explicit deposit due instant (with deposit_required_amount)", "type": "string" }, "deposit_required_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Explicit deposit amount (with deposit_due_at; overrides policy derivation)", "type": "object" }, "external_ref": { "title": "Source-system key (connector loads only; makes creation replay-safe)", "type": "string" }, "guarantee": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "title": "Protection posture (default `none`)", "type": "string" }, "guest_id": { "format": "uuid", "title": "Primary guest", "type": "string", "x-aerandil-references": "hospitality.person" }, "hold_expires_at": { "format": "date-time", "title": "When a `hold` guarantee lapses (required with hold, forbidden otherwise)", "type": "string" }, "market_segment": { "enum": [ "transient", "group", "contract" ], "title": "Demand segment (transient / group / contract)", "type": "string" }, "nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate (omit to price off the grid)", "type": "object" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type (single-room shape; required unless `rooms` is passed)", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "rooms": { "items": { "properties": { "adults": { "type": "integer" }, "children": { "type": "integer" }, "nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "room_type_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.room_type" } }, "required": [ "room_type_id", "adults", "children" ], "type": "object" }, "title": "Per-room slices for a multi-room booking (one reservation_room each)", "type": "array" }, "session_id": { "title": "Shopping session the booking was made in (its first offer's id)", "type": "string" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "Booking channel (defaults to direct_web)", "type": "string" }, "special_requests": { "title": "Special requests (cot, dietary, accessibility, room preferences)", "type": "string" }, "visitor_id": { "title": "The booking engine's key for the browser that booked, when its tag read one", "type": "string" } }, "required": [ "property_id", "guest_id", "rate_plan_id", "arrival_date", "departure_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.reservation_for_property", "hospitality.link.reservation_for_guest", "hospitality.link.reservation_uses_rate_plan", "hospitality.link.reservation_uses_cancellation_policy", "hospitality.link.reservation_for_room_type", "hospitality.link.reservation_has_room", "hospitality.link.reservation_room_for_room_type", "hospitality.link.reservation_room_has_night", "hospitality.link.reservation_night_uses_rate_plan", "hospitality.link.reservation_booked_in_session" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.reservation", "hospitality.reservation_room", "hospitality.reservation_night", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.create_reservation:apply" ] } ], "summary": "Create reservation", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.create_reservation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_create_reservation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.create_reservation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_create_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults": { "title": "Adults (single-room shape; required unless `rooms` is passed)", "type": "integer" }, "arrival_date": { "format": "date", "title": "Arrival", "type": "string" }, "booked_at": { "format": "date-time", "title": "Booking instant (defaults to now; must not be in the future or after arrival)", "type": "string" }, "channel_reference": { "title": "External channel reference (OTA confirmation / GDS locator)", "type": "string" }, "children": { "title": "Children (single-room shape; required unless `rooms` is passed)", "type": "integer" }, "confirmation_number": { "title": "Source-system confirmation number (connector loads only; defaults to a minted R-…)", "type": "string" }, "departure_date": { "format": "date", "title": "Departure", "type": "string" }, "deposit_due_at": { "format": "date-time", "title": "Explicit deposit due instant (with deposit_required_amount)", "type": "string" }, "deposit_required_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Explicit deposit amount (with deposit_due_at; overrides policy derivation)", "type": "object" }, "external_ref": { "title": "Source-system key (connector loads only; makes creation replay-safe)", "type": "string" }, "guarantee": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "title": "Protection posture (default `none`)", "type": "string" }, "guest_id": { "format": "uuid", "title": "Primary guest", "type": "string", "x-aerandil-references": "hospitality.person" }, "hold_expires_at": { "format": "date-time", "title": "When a `hold` guarantee lapses (required with hold, forbidden otherwise)", "type": "string" }, "market_segment": { "enum": [ "transient", "group", "contract" ], "title": "Demand segment (transient / group / contract)", "type": "string" }, "nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate (omit to price off the grid)", "type": "object" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type (single-room shape; required unless `rooms` is passed)", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "rooms": { "items": { "properties": { "adults": { "type": "integer" }, "children": { "type": "integer" }, "nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "room_type_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.room_type" } }, "required": [ "room_type_id", "adults", "children" ], "type": "object" }, "title": "Per-room slices for a multi-room booking (one reservation_room each)", "type": "array" }, "session_id": { "title": "Shopping session the booking was made in (its first offer's id)", "type": "string" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "Booking channel (defaults to direct_web)", "type": "string" }, "special_requests": { "title": "Special requests (cot, dietary, accessibility, room preferences)", "type": "string" }, "visitor_id": { "title": "The booking engine's key for the browser that booked, when its tag read one", "type": "string" } }, "required": [ "property_id", "guest_id", "rate_plan_id", "arrival_date", "departure_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.reservation_for_property", "hospitality.link.reservation_for_guest", "hospitality.link.reservation_uses_rate_plan", "hospitality.link.reservation_uses_cancellation_policy", "hospitality.link.reservation_for_room_type", "hospitality.link.reservation_has_room", "hospitality.link.reservation_room_for_room_type", "hospitality.link.reservation_room_has_night", "hospitality.link.reservation_night_uses_rate_plan", "hospitality.link.reservation_booked_in_session" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.reservation", "hospitality.reservation_room", "hospitality.reservation_night", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Create reservation (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.create_reservation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_create_reservation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_create_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults": { "title": "Adults (single-room shape; required unless `rooms` is passed)", "type": "integer" }, "arrival_date": { "format": "date", "title": "Arrival", "type": "string" }, "booked_at": { "format": "date-time", "title": "Booking instant (defaults to now; must not be in the future or after arrival)", "type": "string" }, "channel_reference": { "title": "External channel reference (OTA confirmation / GDS locator)", "type": "string" }, "children": { "title": "Children (single-room shape; required unless `rooms` is passed)", "type": "integer" }, "confirmation_number": { "title": "Source-system confirmation number (connector loads only; defaults to a minted R-…)", "type": "string" }, "departure_date": { "format": "date", "title": "Departure", "type": "string" }, "deposit_due_at": { "format": "date-time", "title": "Explicit deposit due instant (with deposit_required_amount)", "type": "string" }, "deposit_required_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Explicit deposit amount (with deposit_due_at; overrides policy derivation)", "type": "object" }, "external_ref": { "title": "Source-system key (connector loads only; makes creation replay-safe)", "type": "string" }, "guarantee": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "title": "Protection posture (default `none`)", "type": "string" }, "guest_id": { "format": "uuid", "title": "Primary guest", "type": "string", "x-aerandil-references": "hospitality.person" }, "hold_expires_at": { "format": "date-time", "title": "When a `hold` guarantee lapses (required with hold, forbidden otherwise)", "type": "string" }, "market_segment": { "enum": [ "transient", "group", "contract" ], "title": "Demand segment (transient / group / contract)", "type": "string" }, "nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate (omit to price off the grid)", "type": "object" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type (single-room shape; required unless `rooms` is passed)", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "rooms": { "items": { "properties": { "adults": { "type": "integer" }, "children": { "type": "integer" }, "nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "room_type_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.room_type" } }, "required": [ "room_type_id", "adults", "children" ], "type": "object" }, "title": "Per-room slices for a multi-room booking (one reservation_room each)", "type": "array" }, "session_id": { "title": "Shopping session the booking was made in (its first offer's id)", "type": "string" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "Booking channel (defaults to direct_web)", "type": "string" }, "special_requests": { "title": "Special requests (cot, dietary, accessibility, room preferences)", "type": "string" }, "visitor_id": { "title": "The booking engine's key for the browser that booked, when its tag read one", "type": "string" } }, "required": [ "property_id", "guest_id", "rate_plan_id", "arrival_date", "departure_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Create reservation (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.create_reservation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_create_reservation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.create_reservation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_create_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults": { "title": "Adults (single-room shape; required unless `rooms` is passed)", "type": "integer" }, "arrival_date": { "format": "date", "title": "Arrival", "type": "string" }, "booked_at": { "format": "date-time", "title": "Booking instant (defaults to now; must not be in the future or after arrival)", "type": "string" }, "channel_reference": { "title": "External channel reference (OTA confirmation / GDS locator)", "type": "string" }, "children": { "title": "Children (single-room shape; required unless `rooms` is passed)", "type": "integer" }, "confirmation_number": { "title": "Source-system confirmation number (connector loads only; defaults to a minted R-…)", "type": "string" }, "departure_date": { "format": "date", "title": "Departure", "type": "string" }, "deposit_due_at": { "format": "date-time", "title": "Explicit deposit due instant (with deposit_required_amount)", "type": "string" }, "deposit_required_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Explicit deposit amount (with deposit_due_at; overrides policy derivation)", "type": "object" }, "external_ref": { "title": "Source-system key (connector loads only; makes creation replay-safe)", "type": "string" }, "guarantee": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "title": "Protection posture (default `none`)", "type": "string" }, "guest_id": { "format": "uuid", "title": "Primary guest", "type": "string", "x-aerandil-references": "hospitality.person" }, "hold_expires_at": { "format": "date-time", "title": "When a `hold` guarantee lapses (required with hold, forbidden otherwise)", "type": "string" }, "market_segment": { "enum": [ "transient", "group", "contract" ], "title": "Demand segment (transient / group / contract)", "type": "string" }, "nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate (omit to price off the grid)", "type": "object" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type (single-room shape; required unless `rooms` is passed)", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "rooms": { "items": { "properties": { "adults": { "type": "integer" }, "children": { "type": "integer" }, "nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "room_type_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.room_type" } }, "required": [ "room_type_id", "adults", "children" ], "type": "object" }, "title": "Per-room slices for a multi-room booking (one reservation_room each)", "type": "array" }, "session_id": { "title": "Shopping session the booking was made in (its first offer's id)", "type": "string" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "Booking channel (defaults to direct_web)", "type": "string" }, "special_requests": { "title": "Special requests (cot, dietary, accessibility, room preferences)", "type": "string" }, "visitor_id": { "title": "The booking engine's key for the browser that booked, when its tag read one", "type": "string" } }, "required": [ "property_id", "guest_id", "rate_plan_id", "arrival_date", "departure_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Create reservation (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.create_work_order/apply": { "post": { "description": "Open a maintenance work order against a room, optionally assigning an engineer on the spot. When the room is physically unusable, declare the out-of-order window here (out_of_order_start / out_of_order_end / return_status): the order then holds a real room_status_block minted through the same path as take_room_out_of_order — ledger weight, in-house-guest refusal, conflicting-assignment work list and all — and complete_work_order releases it. Never a severity-driven side effect: downtime is always an explicit declaration. Faults by element (2026-10-15): `element` names the thing in the room that failed (the attendant's word); `fault_type_id` names an entry of the house's or its brand's catalogue and fills `title`, `category`, `severity` and `element` wherever the call states none; with no category from either, the element's trade is the category; with no title, the element's name is the title. An order already open on the room under the same title (case and spacing aside) or the same fault type is that order — the double fault hubOS lists before a new one is raised: nothing is minted, the response carries a `work-order-open-twin` warning naming it, and `work_order.reported_again` records the second report. Two orders naming different assets are not twins; `allow_duplicate` raises another anyway. What the call declares beyond the report lands on the twin (2026-10-17): a declared out-of-order window blocks the room through it when it holds no block (one it holds that already covers the window is said, any other is refused naming it — an order holds one block), and a `staff_member_id` takes it when nobody holds it (a holder it has keeps it — assign_work_order re-points); the warning says which, and `work_order.reported_again` carries `block_id` and `assignee_id`. A fault in a public area is `create_public_area_work_order`.\n\nEffects: create hospitality.work_order; link hospitality.link.work_order_from_triage; link hospitality.link.work_order_for_room; link hospitality.link.work_order_assigned_to; create hospitality.room_status_block; link hospitality.link.room_status_block_for_room; link hospitality.link.work_order_holds_block; modify hospitality.availability_day; link hospitality.link.work_order_for_asset; link hospitality.link.work_order_reported_by_stay; link hospitality.link.work_order_of_fault_type; link hospitality.link.work_order_for_area; modify hospitality.work_order.", "operationId": "apply_hospitality_action_create_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allow_duplicate": { "title": "Raise it even when an order with the same title or fault type is already open on the room", "type": "boolean" }, "asset_id": { "format": "uuid", "title": "The equipment that failed, when the order is for one — it need not stand in the target room (no hot water in 101, the boiler in the plant room); same house, not retired. Linked (work_order_for_asset) and carried on the order as asset_id", "type": "string", "x-aerandil-references": "hospitality.asset" }, "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "Category (defaults to the fault type's, else the element's trade)", "type": "string" }, "description": { "title": "Description", "type": "string" }, "element": { "enum": [ "light", "air_conditioning", "curtain", "safe", "door", "television", "phone", "wardrobe", "shower", "mirror", "toilet", "pipework", "minibar", "electrical", "other" ], "title": "The room element the fault is in (defaults to the fault type's)", "type": "string" }, "fault_type_id": { "format": "uuid", "title": "The catalogue entry the fault is — the house's or its brand's, active; fills what the call does not state", "type": "string", "x-aerandil-references": "hospitality.fault_type" }, "from_triage_id": { "format": "uuid", "title": "The triaged guest report that raised this, if one did — the fault as the guest phrased it, and the edge the closing reply walks back to the conversation", "type": "string", "x-aerandil-references": "hospitality.message_triage" }, "out_of_order_end": { "format": "date", "title": "Last out-of-order night (inclusive through-date; the night audit returns the room when it closes)", "type": "string" }, "out_of_order_start": { "format": "date", "title": "First night the room is out of order (with out_of_order_end and return_status, or not at all)", "type": "string" }, "return_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Housekeeping status the room re-enters on release", "type": "string" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "title": "Severity (defaults to the fault type's)", "type": "string" }, "staff_member_id": { "format": "uuid", "title": "Engineer to assign on creation", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "stay_id": { "format": "uuid", "title": "The guest stay that reported the fault; the order then reads reported_by_guest without carrying the guest", "type": "string", "x-aerandil-references": "hospitality.stay" }, "title": { "title": "Title (defaults to the fault type's, else the element's name)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.work_order_from_triage", "hospitality.link.work_order_for_room", "hospitality.link.work_order_assigned_to", "hospitality.link.room_status_block_for_room", "hospitality.link.work_order_holds_block", "hospitality.link.work_order_for_asset", "hospitality.link.work_order_reported_by_stay", "hospitality.link.work_order_of_fault_type", "hospitality.link.work_order_for_area" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.work_order", "hospitality.room_status_block", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.create_work_order:apply" ] } ], "summary": "Create work order", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.create_work_order/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_create_work_order` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.create_work_order:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_create_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allow_duplicate": { "title": "Raise it even when an order with the same title or fault type is already open on the room", "type": "boolean" }, "asset_id": { "format": "uuid", "title": "The equipment that failed, when the order is for one — it need not stand in the target room (no hot water in 101, the boiler in the plant room); same house, not retired. Linked (work_order_for_asset) and carried on the order as asset_id", "type": "string", "x-aerandil-references": "hospitality.asset" }, "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "Category (defaults to the fault type's, else the element's trade)", "type": "string" }, "description": { "title": "Description", "type": "string" }, "element": { "enum": [ "light", "air_conditioning", "curtain", "safe", "door", "television", "phone", "wardrobe", "shower", "mirror", "toilet", "pipework", "minibar", "electrical", "other" ], "title": "The room element the fault is in (defaults to the fault type's)", "type": "string" }, "fault_type_id": { "format": "uuid", "title": "The catalogue entry the fault is — the house's or its brand's, active; fills what the call does not state", "type": "string", "x-aerandil-references": "hospitality.fault_type" }, "from_triage_id": { "format": "uuid", "title": "The triaged guest report that raised this, if one did — the fault as the guest phrased it, and the edge the closing reply walks back to the conversation", "type": "string", "x-aerandil-references": "hospitality.message_triage" }, "out_of_order_end": { "format": "date", "title": "Last out-of-order night (inclusive through-date; the night audit returns the room when it closes)", "type": "string" }, "out_of_order_start": { "format": "date", "title": "First night the room is out of order (with out_of_order_end and return_status, or not at all)", "type": "string" }, "return_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Housekeeping status the room re-enters on release", "type": "string" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "title": "Severity (defaults to the fault type's)", "type": "string" }, "staff_member_id": { "format": "uuid", "title": "Engineer to assign on creation", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "stay_id": { "format": "uuid", "title": "The guest stay that reported the fault; the order then reads reported_by_guest without carrying the guest", "type": "string", "x-aerandil-references": "hospitality.stay" }, "title": { "title": "Title (defaults to the fault type's, else the element's name)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.work_order_from_triage", "hospitality.link.work_order_for_room", "hospitality.link.work_order_assigned_to", "hospitality.link.room_status_block_for_room", "hospitality.link.work_order_holds_block", "hospitality.link.work_order_for_asset", "hospitality.link.work_order_reported_by_stay", "hospitality.link.work_order_of_fault_type", "hospitality.link.work_order_for_area" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.work_order", "hospitality.room_status_block", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Create work order (dry-run)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.create_work_order/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_create_work_order`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_create_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allow_duplicate": { "title": "Raise it even when an order with the same title or fault type is already open on the room", "type": "boolean" }, "asset_id": { "format": "uuid", "title": "The equipment that failed, when the order is for one — it need not stand in the target room (no hot water in 101, the boiler in the plant room); same house, not retired. Linked (work_order_for_asset) and carried on the order as asset_id", "type": "string", "x-aerandil-references": "hospitality.asset" }, "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "Category (defaults to the fault type's, else the element's trade)", "type": "string" }, "description": { "title": "Description", "type": "string" }, "element": { "enum": [ "light", "air_conditioning", "curtain", "safe", "door", "television", "phone", "wardrobe", "shower", "mirror", "toilet", "pipework", "minibar", "electrical", "other" ], "title": "The room element the fault is in (defaults to the fault type's)", "type": "string" }, "fault_type_id": { "format": "uuid", "title": "The catalogue entry the fault is — the house's or its brand's, active; fills what the call does not state", "type": "string", "x-aerandil-references": "hospitality.fault_type" }, "from_triage_id": { "format": "uuid", "title": "The triaged guest report that raised this, if one did — the fault as the guest phrased it, and the edge the closing reply walks back to the conversation", "type": "string", "x-aerandil-references": "hospitality.message_triage" }, "out_of_order_end": { "format": "date", "title": "Last out-of-order night (inclusive through-date; the night audit returns the room when it closes)", "type": "string" }, "out_of_order_start": { "format": "date", "title": "First night the room is out of order (with out_of_order_end and return_status, or not at all)", "type": "string" }, "return_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Housekeeping status the room re-enters on release", "type": "string" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "title": "Severity (defaults to the fault type's)", "type": "string" }, "staff_member_id": { "format": "uuid", "title": "Engineer to assign on creation", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "stay_id": { "format": "uuid", "title": "The guest stay that reported the fault; the order then reads reported_by_guest without carrying the guest", "type": "string", "x-aerandil-references": "hospitality.stay" }, "title": { "title": "Title (defaults to the fault type's, else the element's name)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Create work order (dry-run)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.create_work_order/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_create_work_order` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.create_work_order:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_create_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allow_duplicate": { "title": "Raise it even when an order with the same title or fault type is already open on the room", "type": "boolean" }, "asset_id": { "format": "uuid", "title": "The equipment that failed, when the order is for one — it need not stand in the target room (no hot water in 101, the boiler in the plant room); same house, not retired. Linked (work_order_for_asset) and carried on the order as asset_id", "type": "string", "x-aerandil-references": "hospitality.asset" }, "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "Category (defaults to the fault type's, else the element's trade)", "type": "string" }, "description": { "title": "Description", "type": "string" }, "element": { "enum": [ "light", "air_conditioning", "curtain", "safe", "door", "television", "phone", "wardrobe", "shower", "mirror", "toilet", "pipework", "minibar", "electrical", "other" ], "title": "The room element the fault is in (defaults to the fault type's)", "type": "string" }, "fault_type_id": { "format": "uuid", "title": "The catalogue entry the fault is — the house's or its brand's, active; fills what the call does not state", "type": "string", "x-aerandil-references": "hospitality.fault_type" }, "from_triage_id": { "format": "uuid", "title": "The triaged guest report that raised this, if one did — the fault as the guest phrased it, and the edge the closing reply walks back to the conversation", "type": "string", "x-aerandil-references": "hospitality.message_triage" }, "out_of_order_end": { "format": "date", "title": "Last out-of-order night (inclusive through-date; the night audit returns the room when it closes)", "type": "string" }, "out_of_order_start": { "format": "date", "title": "First night the room is out of order (with out_of_order_end and return_status, or not at all)", "type": "string" }, "return_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Housekeeping status the room re-enters on release", "type": "string" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "title": "Severity (defaults to the fault type's)", "type": "string" }, "staff_member_id": { "format": "uuid", "title": "Engineer to assign on creation", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "stay_id": { "format": "uuid", "title": "The guest stay that reported the fault; the order then reads reported_by_guest without carrying the guest", "type": "string", "x-aerandil-references": "hospitality.stay" }, "title": { "title": "Title (defaults to the fault type's, else the element's name)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Create work order (rollup delta)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.decide_approval_gate/apply": { "post": { "description": "Record a human approval decision. Inserts an `approval_decision`, validates `approval_gate_eligible_decider` and `approval_decision_context_hash_matches`, recomputes gate status per the strategy, and on `approved` transitions the guarded step to `ready`. Agent decisions can be recorded for audit but cannot satisfy human-required gates (`approval_gate_agent_cannot_satisfy_human_gate`). Supersession uses the `approval_decision_supersedes_decision` self-link, constrained to same-approver / non-terminal decisions (`approval_decision_supersedes_same_approver_only`).\n\nEffects: create hospitality.approval_decision; modify hospitality.approval_gate; modify hospitality.workflow_step_run; link hospitality.link.approval_decision_for_gate; link hospitality.link.approval_decision_supersedes_decision; modify hospitality.owner_statement; modify hospitality.property_budget; modify hospitality.purpose_grant; modify hospitality.workflow_run.", "operationId": "apply_hospitality_action_decide_approval_gate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "context_hash": { "title": "Must match the gate's current context hash", "type": "string" }, "decision": { "enum": [ "approve", "reject", "request_changes", "delegate", "abstain" ], "title": "Decision value", "type": "string" }, "decision_note": { "title": "Bounded to 1024 chars", "type": "string" }, "delegate_to_principal_id": { "title": "Required for decision = delegate", "type": "string" }, "external_reference": { "title": "Slack interaction id, Linear comment id, etc.", "type": "string" }, "supersedes_decision_id": { "title": "Optional pointer to a prior non-terminal decision by the same approver", "type": "string" } }, "required": [ "decision", "context_hash" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.approval_gate" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.approval_decision_for_gate", "hospitality.link.approval_decision_supersedes_decision" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.approval_decision", "hospitality.approval_gate", "hospitality.workflow_step_run", "hospitality.owner_statement", "hospitality.property_budget", "hospitality.purpose_grant", "hospitality.workflow_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.decide_approval_gate:apply" ] } ], "summary": "Decide approval gate", "tags": [ "approvals" ] } }, "/v1/actions/hospitality.action.decide_approval_gate/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_decide_approval_gate` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.decide_approval_gate:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_decide_approval_gate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "context_hash": { "title": "Must match the gate's current context hash", "type": "string" }, "decision": { "enum": [ "approve", "reject", "request_changes", "delegate", "abstain" ], "title": "Decision value", "type": "string" }, "decision_note": { "title": "Bounded to 1024 chars", "type": "string" }, "delegate_to_principal_id": { "title": "Required for decision = delegate", "type": "string" }, "external_reference": { "title": "Slack interaction id, Linear comment id, etc.", "type": "string" }, "supersedes_decision_id": { "title": "Optional pointer to a prior non-terminal decision by the same approver", "type": "string" } }, "required": [ "decision", "context_hash" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.approval_gate" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.approval_decision_for_gate", "hospitality.link.approval_decision_supersedes_decision" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.approval_decision", "hospitality.approval_gate", "hospitality.workflow_step_run", "hospitality.owner_statement", "hospitality.property_budget", "hospitality.purpose_grant", "hospitality.workflow_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Decide approval gate (dry-run)", "tags": [ "approvals" ] } }, "/v1/actions/hospitality.action.decide_approval_gate/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_decide_approval_gate`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_decide_approval_gate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "context_hash": { "title": "Must match the gate's current context hash", "type": "string" }, "decision": { "enum": [ "approve", "reject", "request_changes", "delegate", "abstain" ], "title": "Decision value", "type": "string" }, "decision_note": { "title": "Bounded to 1024 chars", "type": "string" }, "delegate_to_principal_id": { "title": "Required for decision = delegate", "type": "string" }, "external_reference": { "title": "Slack interaction id, Linear comment id, etc.", "type": "string" }, "supersedes_decision_id": { "title": "Optional pointer to a prior non-terminal decision by the same approver", "type": "string" } }, "required": [ "decision", "context_hash" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.approval_gate" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Decide approval gate (dry-run)", "tags": [ "approvals" ] } }, "/v1/actions/hospitality.action.decide_approval_gate/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_decide_approval_gate` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.decide_approval_gate:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_decide_approval_gate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "context_hash": { "title": "Must match the gate's current context hash", "type": "string" }, "decision": { "enum": [ "approve", "reject", "request_changes", "delegate", "abstain" ], "title": "Decision value", "type": "string" }, "decision_note": { "title": "Bounded to 1024 chars", "type": "string" }, "delegate_to_principal_id": { "title": "Required for decision = delegate", "type": "string" }, "external_reference": { "title": "Slack interaction id, Linear comment id, etc.", "type": "string" }, "supersedes_decision_id": { "title": "Optional pointer to a prior non-terminal decision by the same approver", "type": "string" } }, "required": [ "decision", "context_hash" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.approval_gate" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Decide approval gate (rollup delta)", "tags": [ "approvals" ] } }, "/v1/actions/hospitality.action.decline_group_request/apply": { "post": { "description": "Mark a group_request as `lost`. Records the decline reason.\n\nEffects: modify hospitality.group_request.", "operationId": "apply_hospitality_action_decline_group_request", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Reason for declining", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_request" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.group_request" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.decline_group_request:apply" ] } ], "summary": "Decline group request", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.decline_group_request/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_decline_group_request` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.decline_group_request:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_decline_group_request", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Reason for declining", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_request" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.group_request" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Decline group request (dry-run)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.decline_group_request/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_decline_group_request`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_decline_group_request", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Reason for declining", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_request" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Decline group request (dry-run)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.decline_group_request/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_decline_group_request` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.decline_group_request:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_decline_group_request", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Reason for declining", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_request" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Decline group request (rollup delta)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.define_access_purpose/apply": { "post": { "description": "Create an `access_purpose` — the PBAC vocabulary entry naming which marking compartments it can unlock and how long a grant of it may live. Active immediately (a purpose is a definition, not a permission; nothing is conferred until a grant is approved). Emits `access_purpose.defined`.\n\nEffects: create hospitality.access_purpose.", "operationId": "apply_hospitality_action_define_access_purpose", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "covered_markings": { "title": "Marking api-names this purpose can unlock (JSON array)" }, "display_name": { "title": "Operator-facing name", "type": "string" }, "justification": { "title": "The standing business/legal ground for this purpose", "type": "string" }, "max_grant_hours": { "title": "Ceiling on a grant's lifetime under this purpose", "type": "integer" } }, "required": [ "display_name", "justification", "covered_markings" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.access_purpose" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.define_access_purpose:apply" ] } ], "summary": "Define access purpose", "tags": [ "pbac" ] } }, "/v1/actions/hospitality.action.define_access_purpose/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_define_access_purpose` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.define_access_purpose:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_define_access_purpose", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "covered_markings": { "title": "Marking api-names this purpose can unlock (JSON array)" }, "display_name": { "title": "Operator-facing name", "type": "string" }, "justification": { "title": "The standing business/legal ground for this purpose", "type": "string" }, "max_grant_hours": { "title": "Ceiling on a grant's lifetime under this purpose", "type": "integer" } }, "required": [ "display_name", "justification", "covered_markings" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.access_purpose" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Define access purpose (dry-run)", "tags": [ "pbac" ] } }, "/v1/actions/hospitality.action.define_access_purpose/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_define_access_purpose`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_define_access_purpose", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "covered_markings": { "title": "Marking api-names this purpose can unlock (JSON array)" }, "display_name": { "title": "Operator-facing name", "type": "string" }, "justification": { "title": "The standing business/legal ground for this purpose", "type": "string" }, "max_grant_hours": { "title": "Ceiling on a grant's lifetime under this purpose", "type": "integer" } }, "required": [ "display_name", "justification", "covered_markings" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Define access purpose (dry-run)", "tags": [ "pbac" ] } }, "/v1/actions/hospitality.action.define_access_purpose/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_define_access_purpose` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.define_access_purpose:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_define_access_purpose", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "covered_markings": { "title": "Marking api-names this purpose can unlock (JSON array)" }, "display_name": { "title": "Operator-facing name", "type": "string" }, "justification": { "title": "The standing business/legal ground for this purpose", "type": "string" }, "max_grant_hours": { "title": "Ceiling on a grant's lifetime under this purpose", "type": "integer" } }, "required": [ "display_name", "justification", "covered_markings" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Define access purpose (rollup delta)", "tags": [ "pbac" ] } }, "/v1/actions/hospitality.action.define_automation/apply": { "post": { "description": "Create an `automation` monitor→effect rule in `draft`. The condition is an object-set filter over a watched object type (evaluated against the event tail), a named domain event (`event_named`, filtered and templated on its payload), or a cron schedule; the effect fires a registered action, calls a read-only function, or sends a notification. `requires_approval` routes the effect through a 0020 approval_gate instead of applying. Coherence (condition vs. kind, effect vs. kind, approval vs. policy) is enforced by the `automation` validator. Created inert — nothing fires until `activate_automation`. Emits `automation.defined`.\n\nEffects: create hospitality.automation.", "operationId": "apply_hospitality_action_define_automation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "approval_policy_ref": { "title": "Approval policy the staged gate opens under (required when requires_approval)", "type": "string" }, "condition_kind": { "enum": [ "object_set_added", "object_set_removed", "object_set_modified", "object_set_all", "time_cron", "event_named" ], "title": "Trigger-predicate class", "type": "string" }, "cron_expression": { "title": "Schedule for time_cron (5-field cron)", "type": "string" }, "description_text": { "title": "What this automation is for", "type": "string" }, "display_name": { "title": "Human-readable name shown in the operator console", "type": "string" }, "effect_action": { "title": "Registered action to fire (for apply_action)", "type": "string" }, "effect_function": { "title": "Read-only function to invoke (for call_function)", "type": "string" }, "effect_kind": { "enum": [ "apply_action", "call_function", "send_notification" ], "title": "Effect fired when the condition is met", "type": "string" }, "effect_notification_template": { "title": "Templated notification body/target (for send_notification, JSON)" }, "effect_params_template": { "additionalProperties": true, "title": "Template mapping triggering-object fields → effect input (JSON)", "type": "object" }, "event_type_ref": { "title": "Named domain event watched (required for event_named)", "type": "string" }, "execution_mode": { "enum": [ "per_object", "batch" ], "title": "Per-object vs batch effect firing (default per_object)", "type": "string" }, "max_cascade_depth": { "title": "Loop guard: max trigger-chain depth before suppression (default 3)", "type": "integer" }, "modified_property_watch": { "title": "Property api-names whose change trips object_set_modified (JSON array)" }, "object_set_filter": { "title": "Search-filter predicate defining the watched object set (JSON)" }, "object_type_ref": { "title": "Watched object type (required for object_set_* kinds)", "type": "string" }, "requires_approval": { "title": "Route the effect through a 0020 approval_gate instead of applying", "type": "boolean" } }, "required": [ "display_name", "condition_kind", "effect_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.automation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.define_automation:apply" ] } ], "summary": "Define automation", "tags": [ "automation" ] } }, "/v1/actions/hospitality.action.define_automation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_define_automation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.define_automation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_define_automation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "approval_policy_ref": { "title": "Approval policy the staged gate opens under (required when requires_approval)", "type": "string" }, "condition_kind": { "enum": [ "object_set_added", "object_set_removed", "object_set_modified", "object_set_all", "time_cron", "event_named" ], "title": "Trigger-predicate class", "type": "string" }, "cron_expression": { "title": "Schedule for time_cron (5-field cron)", "type": "string" }, "description_text": { "title": "What this automation is for", "type": "string" }, "display_name": { "title": "Human-readable name shown in the operator console", "type": "string" }, "effect_action": { "title": "Registered action to fire (for apply_action)", "type": "string" }, "effect_function": { "title": "Read-only function to invoke (for call_function)", "type": "string" }, "effect_kind": { "enum": [ "apply_action", "call_function", "send_notification" ], "title": "Effect fired when the condition is met", "type": "string" }, "effect_notification_template": { "title": "Templated notification body/target (for send_notification, JSON)" }, "effect_params_template": { "additionalProperties": true, "title": "Template mapping triggering-object fields → effect input (JSON)", "type": "object" }, "event_type_ref": { "title": "Named domain event watched (required for event_named)", "type": "string" }, "execution_mode": { "enum": [ "per_object", "batch" ], "title": "Per-object vs batch effect firing (default per_object)", "type": "string" }, "max_cascade_depth": { "title": "Loop guard: max trigger-chain depth before suppression (default 3)", "type": "integer" }, "modified_property_watch": { "title": "Property api-names whose change trips object_set_modified (JSON array)" }, "object_set_filter": { "title": "Search-filter predicate defining the watched object set (JSON)" }, "object_type_ref": { "title": "Watched object type (required for object_set_* kinds)", "type": "string" }, "requires_approval": { "title": "Route the effect through a 0020 approval_gate instead of applying", "type": "boolean" } }, "required": [ "display_name", "condition_kind", "effect_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.automation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Define automation (dry-run)", "tags": [ "automation" ] } }, "/v1/actions/hospitality.action.define_automation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_define_automation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_define_automation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "approval_policy_ref": { "title": "Approval policy the staged gate opens under (required when requires_approval)", "type": "string" }, "condition_kind": { "enum": [ "object_set_added", "object_set_removed", "object_set_modified", "object_set_all", "time_cron", "event_named" ], "title": "Trigger-predicate class", "type": "string" }, "cron_expression": { "title": "Schedule for time_cron (5-field cron)", "type": "string" }, "description_text": { "title": "What this automation is for", "type": "string" }, "display_name": { "title": "Human-readable name shown in the operator console", "type": "string" }, "effect_action": { "title": "Registered action to fire (for apply_action)", "type": "string" }, "effect_function": { "title": "Read-only function to invoke (for call_function)", "type": "string" }, "effect_kind": { "enum": [ "apply_action", "call_function", "send_notification" ], "title": "Effect fired when the condition is met", "type": "string" }, "effect_notification_template": { "title": "Templated notification body/target (for send_notification, JSON)" }, "effect_params_template": { "additionalProperties": true, "title": "Template mapping triggering-object fields → effect input (JSON)", "type": "object" }, "event_type_ref": { "title": "Named domain event watched (required for event_named)", "type": "string" }, "execution_mode": { "enum": [ "per_object", "batch" ], "title": "Per-object vs batch effect firing (default per_object)", "type": "string" }, "max_cascade_depth": { "title": "Loop guard: max trigger-chain depth before suppression (default 3)", "type": "integer" }, "modified_property_watch": { "title": "Property api-names whose change trips object_set_modified (JSON array)" }, "object_set_filter": { "title": "Search-filter predicate defining the watched object set (JSON)" }, "object_type_ref": { "title": "Watched object type (required for object_set_* kinds)", "type": "string" }, "requires_approval": { "title": "Route the effect through a 0020 approval_gate instead of applying", "type": "boolean" } }, "required": [ "display_name", "condition_kind", "effect_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Define automation (dry-run)", "tags": [ "automation" ] } }, "/v1/actions/hospitality.action.define_automation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_define_automation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.define_automation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_define_automation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "approval_policy_ref": { "title": "Approval policy the staged gate opens under (required when requires_approval)", "type": "string" }, "condition_kind": { "enum": [ "object_set_added", "object_set_removed", "object_set_modified", "object_set_all", "time_cron", "event_named" ], "title": "Trigger-predicate class", "type": "string" }, "cron_expression": { "title": "Schedule for time_cron (5-field cron)", "type": "string" }, "description_text": { "title": "What this automation is for", "type": "string" }, "display_name": { "title": "Human-readable name shown in the operator console", "type": "string" }, "effect_action": { "title": "Registered action to fire (for apply_action)", "type": "string" }, "effect_function": { "title": "Read-only function to invoke (for call_function)", "type": "string" }, "effect_kind": { "enum": [ "apply_action", "call_function", "send_notification" ], "title": "Effect fired when the condition is met", "type": "string" }, "effect_notification_template": { "title": "Templated notification body/target (for send_notification, JSON)" }, "effect_params_template": { "additionalProperties": true, "title": "Template mapping triggering-object fields → effect input (JSON)", "type": "object" }, "event_type_ref": { "title": "Named domain event watched (required for event_named)", "type": "string" }, "execution_mode": { "enum": [ "per_object", "batch" ], "title": "Per-object vs batch effect firing (default per_object)", "type": "string" }, "max_cascade_depth": { "title": "Loop guard: max trigger-chain depth before suppression (default 3)", "type": "integer" }, "modified_property_watch": { "title": "Property api-names whose change trips object_set_modified (JSON array)" }, "object_set_filter": { "title": "Search-filter predicate defining the watched object set (JSON)" }, "object_type_ref": { "title": "Watched object type (required for object_set_* kinds)", "type": "string" }, "requires_approval": { "title": "Route the effect through a 0020 approval_gate instead of applying", "type": "boolean" } }, "required": [ "display_name", "condition_kind", "effect_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Define automation (rollup delta)", "tags": [ "automation" ] } }, "/v1/actions/hospitality.action.define_checklist_template/apply": { "post": { "description": "Define the checklist for one housekeeping task type — and optionally one room type — as a brand standard (`brand_id`) or the house's own (`property_id`; exactly one of the two). `items` are the list in order, each a stable `code`, the `label` the attendant reads and its `kind`: `check` (a tick; the only kind the score counts), `photo` (attached to the result), `count` or `text`. `required` makes `complete_housekeeping_task` refuse until a result for this template is recorded against the task. Replay-safe by its business key (scope, task type, room type): the same key again revises the active template's name, items and `required` in place (an identical repeat writes nothing); after `retire_checklist_template`, the key mints a new template. A public-area task type's list may name `area_kind` instead of a room type (2026-10-14) — every corridor's, the pool's — and the key is then (scope, task type, area kind). Emits `checklist_template.defined`.\n\nEffects: create hospitality.checklist_template; modify hospitality.checklist_template; link hospitality.link.checklist_template_at_brand; link hospitality.link.checklist_template_at_property; link hospitality.link.checklist_template_for_room_type.", "operationId": "apply_hospitality_action_define_checklist_template", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "area_kind": { "enum": [ "lobby", "corridor", "lift", "stairwell", "pool", "gym", "spa_area", "restaurant_floor", "toilets", "back_of_house", "exterior", "other" ], "title": "The one kind of public area the list is for — a public-area task type only, never with room_type_id (absent: every area)", "type": "string" }, "brand_id": { "format": "uuid", "title": "Brand scope (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.brand" }, "items": { "items": { "properties": { "code": { "type": "string" }, "kind": { "enum": [ "check", "photo", "count", "text" ], "type": "string" }, "label": { "type": "string" } }, "required": [ "code", "label", "kind" ], "type": "object" }, "title": "Checklist items", "type": "array" }, "name": { "title": "What the list is called on the handset", "type": "string" }, "property_id": { "format": "uuid", "title": "Property scope (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.property" }, "required": { "title": "Refuse task completion until a result is recorded (default false)", "type": "boolean" }, "room_type_id": { "format": "uuid", "title": "The one room type the list is for (absent: every room)", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "task_type": { "enum": [ "stayover", "departure", "vacant_pickup", "deep_clean", "turndown", "inspection", "public_area_clean", "public_area_inspection", "minibar", "laundry" ], "title": "The housekeeping task type the list is for", "type": "string" } }, "required": [ "name", "task_type", "items" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.checklist_template_at_brand", "hospitality.link.checklist_template_at_property", "hospitality.link.checklist_template_for_room_type" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.checklist_template" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.define_checklist_template:apply" ] } ], "summary": "Define checklist template", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.define_checklist_template/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_define_checklist_template` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.define_checklist_template:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_define_checklist_template", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "area_kind": { "enum": [ "lobby", "corridor", "lift", "stairwell", "pool", "gym", "spa_area", "restaurant_floor", "toilets", "back_of_house", "exterior", "other" ], "title": "The one kind of public area the list is for — a public-area task type only, never with room_type_id (absent: every area)", "type": "string" }, "brand_id": { "format": "uuid", "title": "Brand scope (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.brand" }, "items": { "items": { "properties": { "code": { "type": "string" }, "kind": { "enum": [ "check", "photo", "count", "text" ], "type": "string" }, "label": { "type": "string" } }, "required": [ "code", "label", "kind" ], "type": "object" }, "title": "Checklist items", "type": "array" }, "name": { "title": "What the list is called on the handset", "type": "string" }, "property_id": { "format": "uuid", "title": "Property scope (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.property" }, "required": { "title": "Refuse task completion until a result is recorded (default false)", "type": "boolean" }, "room_type_id": { "format": "uuid", "title": "The one room type the list is for (absent: every room)", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "task_type": { "enum": [ "stayover", "departure", "vacant_pickup", "deep_clean", "turndown", "inspection", "public_area_clean", "public_area_inspection", "minibar", "laundry" ], "title": "The housekeeping task type the list is for", "type": "string" } }, "required": [ "name", "task_type", "items" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.checklist_template_at_brand", "hospitality.link.checklist_template_at_property", "hospitality.link.checklist_template_for_room_type" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.checklist_template" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Define checklist template (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.define_checklist_template/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_define_checklist_template`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_define_checklist_template", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "area_kind": { "enum": [ "lobby", "corridor", "lift", "stairwell", "pool", "gym", "spa_area", "restaurant_floor", "toilets", "back_of_house", "exterior", "other" ], "title": "The one kind of public area the list is for — a public-area task type only, never with room_type_id (absent: every area)", "type": "string" }, "brand_id": { "format": "uuid", "title": "Brand scope (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.brand" }, "items": { "items": { "properties": { "code": { "type": "string" }, "kind": { "enum": [ "check", "photo", "count", "text" ], "type": "string" }, "label": { "type": "string" } }, "required": [ "code", "label", "kind" ], "type": "object" }, "title": "Checklist items", "type": "array" }, "name": { "title": "What the list is called on the handset", "type": "string" }, "property_id": { "format": "uuid", "title": "Property scope (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.property" }, "required": { "title": "Refuse task completion until a result is recorded (default false)", "type": "boolean" }, "room_type_id": { "format": "uuid", "title": "The one room type the list is for (absent: every room)", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "task_type": { "enum": [ "stayover", "departure", "vacant_pickup", "deep_clean", "turndown", "inspection", "public_area_clean", "public_area_inspection", "minibar", "laundry" ], "title": "The housekeeping task type the list is for", "type": "string" } }, "required": [ "name", "task_type", "items" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Define checklist template (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.define_checklist_template/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_define_checklist_template` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.define_checklist_template:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_define_checklist_template", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "area_kind": { "enum": [ "lobby", "corridor", "lift", "stairwell", "pool", "gym", "spa_area", "restaurant_floor", "toilets", "back_of_house", "exterior", "other" ], "title": "The one kind of public area the list is for — a public-area task type only, never with room_type_id (absent: every area)", "type": "string" }, "brand_id": { "format": "uuid", "title": "Brand scope (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.brand" }, "items": { "items": { "properties": { "code": { "type": "string" }, "kind": { "enum": [ "check", "photo", "count", "text" ], "type": "string" }, "label": { "type": "string" } }, "required": [ "code", "label", "kind" ], "type": "object" }, "title": "Checklist items", "type": "array" }, "name": { "title": "What the list is called on the handset", "type": "string" }, "property_id": { "format": "uuid", "title": "Property scope (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.property" }, "required": { "title": "Refuse task completion until a result is recorded (default false)", "type": "boolean" }, "room_type_id": { "format": "uuid", "title": "The one room type the list is for (absent: every room)", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "task_type": { "enum": [ "stayover", "departure", "vacant_pickup", "deep_clean", "turndown", "inspection", "public_area_clean", "public_area_inspection", "minibar", "laundry" ], "title": "The housekeeping task type the list is for", "type": "string" } }, "required": [ "name", "task_type", "items" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Define checklist template (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.define_fault_type/apply": { "post": { "description": "Put a kind of fault in a catalogue under its code — a brand's (brand_id, shared by its houses) or one house's (property_id); exactly one. It carries the `title` an order raised from it is given, the room `element` it is in (optional — a lift that sticks is in no room), the `category` (the trade that mends it; defaults to the element's trade when an element is named) and the `severity` it starts at. Defining a code the catalogue already holds re-states it in place (details replaced, an unstated optional detail cleared), so the call is replay-safe and is also how an entry is corrected; an identical re-statement changes nothing. A retired code refuses. Emits `fault_type.defined`.\n\nEffects: create hospitality.fault_type; modify hospitality.fault_type; link hospitality.link.fault_type_at_brand; link hospitality.link.fault_type_at_property.", "operationId": "apply_hospitality_action_define_fault_type", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "brand_id": { "format": "uuid", "title": "The brand's catalogue (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.brand" }, "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "The trade that mends it (defaults to the element's)", "type": "string" }, "code": { "title": "The catalogue's code for it", "type": "string" }, "description": { "title": "Notes for whoever raises or mends it", "type": "string" }, "element": { "enum": [ "light", "air_conditioning", "curtain", "safe", "door", "television", "phone", "wardrobe", "shower", "mirror", "toilet", "pipework", "minibar", "electrical", "other" ], "title": "The room element the fault is in", "type": "string" }, "property_id": { "format": "uuid", "title": "One house's catalogue (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.property" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "title": "The severity an order raised from it starts at", "type": "string" }, "title": { "title": "The title an order raised from it is given", "type": "string" } }, "required": [ "code", "title", "severity" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.fault_type_at_brand", "hospitality.link.fault_type_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.fault_type" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.define_fault_type:apply" ] } ], "summary": "Define fault type", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.define_fault_type/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_define_fault_type` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.define_fault_type:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_define_fault_type", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "brand_id": { "format": "uuid", "title": "The brand's catalogue (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.brand" }, "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "The trade that mends it (defaults to the element's)", "type": "string" }, "code": { "title": "The catalogue's code for it", "type": "string" }, "description": { "title": "Notes for whoever raises or mends it", "type": "string" }, "element": { "enum": [ "light", "air_conditioning", "curtain", "safe", "door", "television", "phone", "wardrobe", "shower", "mirror", "toilet", "pipework", "minibar", "electrical", "other" ], "title": "The room element the fault is in", "type": "string" }, "property_id": { "format": "uuid", "title": "One house's catalogue (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.property" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "title": "The severity an order raised from it starts at", "type": "string" }, "title": { "title": "The title an order raised from it is given", "type": "string" } }, "required": [ "code", "title", "severity" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.fault_type_at_brand", "hospitality.link.fault_type_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.fault_type" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Define fault type (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.define_fault_type/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_define_fault_type`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_define_fault_type", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "brand_id": { "format": "uuid", "title": "The brand's catalogue (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.brand" }, "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "The trade that mends it (defaults to the element's)", "type": "string" }, "code": { "title": "The catalogue's code for it", "type": "string" }, "description": { "title": "Notes for whoever raises or mends it", "type": "string" }, "element": { "enum": [ "light", "air_conditioning", "curtain", "safe", "door", "television", "phone", "wardrobe", "shower", "mirror", "toilet", "pipework", "minibar", "electrical", "other" ], "title": "The room element the fault is in", "type": "string" }, "property_id": { "format": "uuid", "title": "One house's catalogue (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.property" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "title": "The severity an order raised from it starts at", "type": "string" }, "title": { "title": "The title an order raised from it is given", "type": "string" } }, "required": [ "code", "title", "severity" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Define fault type (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.define_fault_type/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_define_fault_type` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.define_fault_type:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_define_fault_type", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "brand_id": { "format": "uuid", "title": "The brand's catalogue (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.brand" }, "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "The trade that mends it (defaults to the element's)", "type": "string" }, "code": { "title": "The catalogue's code for it", "type": "string" }, "description": { "title": "Notes for whoever raises or mends it", "type": "string" }, "element": { "enum": [ "light", "air_conditioning", "curtain", "safe", "door", "television", "phone", "wardrobe", "shower", "mirror", "toilet", "pipework", "minibar", "electrical", "other" ], "title": "The room element the fault is in", "type": "string" }, "property_id": { "format": "uuid", "title": "One house's catalogue (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.property" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "title": "The severity an order raised from it starts at", "type": "string" }, "title": { "title": "The title an order raised from it is given", "type": "string" } }, "required": [ "code", "title", "severity" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Define fault type (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.define_feedback_label/apply": { "post": { "description": "Define one of the house's guest-feedback labels — hubOS's quality labels — under its `code`, with the `name` the desk and the floor read. The same code again re-states it in place (a new name, or `status: retired` to stop it going on feedback, or `status: active` to revive it); an identical statement writes nothing. A retired label stays on the feedback it was put on. Emits `feedback_label.defined`.\n\nEffects: create hospitality.feedback_label; modify hospitality.feedback_label; link hospitality.link.feedback_label_at_property.", "operationId": "apply_hospitality_action_define_feedback_label", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "code": { "title": "The house's code for the label (unique within the house)", "type": "string" }, "name": { "title": "The label in words", "type": "string" }, "status": { "enum": [ "active", "retired" ], "title": "active (the default) or retired", "type": "string" } }, "required": [ "code", "name" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.feedback_label_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.feedback_label" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.define_feedback_label:apply" ] } ], "summary": "Define feedback label", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.define_feedback_label/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_define_feedback_label` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.define_feedback_label:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_define_feedback_label", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "code": { "title": "The house's code for the label (unique within the house)", "type": "string" }, "name": { "title": "The label in words", "type": "string" }, "status": { "enum": [ "active", "retired" ], "title": "active (the default) or retired", "type": "string" } }, "required": [ "code", "name" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.feedback_label_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.feedback_label" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Define feedback label (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.define_feedback_label/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_define_feedback_label`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_define_feedback_label", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "code": { "title": "The house's code for the label (unique within the house)", "type": "string" }, "name": { "title": "The label in words", "type": "string" }, "status": { "enum": [ "active", "retired" ], "title": "active (the default) or retired", "type": "string" } }, "required": [ "code", "name" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Define feedback label (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.define_feedback_label/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_define_feedback_label` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.define_feedback_label:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_define_feedback_label", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "code": { "title": "The house's code for the label (unique within the house)", "type": "string" }, "name": { "title": "The label in words", "type": "string" }, "status": { "enum": [ "active", "retired" ], "title": "active (the default) or retired", "type": "string" } }, "required": [ "code", "name" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Define feedback label (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.define_grounding_scope/apply": { "post": { "description": "Create or replace a `grounding_scope` — the admin-curated grounding bundle an agent definition references (grounding_scope_ref, D11). Tenant-scoped, no anchor. A re-define under the same scope_key supersedes the prior scope's curated subset + instructions; verified invocations are added incrementally via add_verified_invocation. Emits `grounding_scope.defined`.\n\nEffects: create hospitality.grounding_scope.", "operationId": "apply_hospitality_action_define_grounding_scope", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "instructions": { "title": "Curator instructions injected into the retrieval context", "type": "string" }, "metric_refs": { "title": "MetricDef names in scope (JSON array)" }, "object_type_refs": { "title": "Object-type api-names in scope (JSON array)" }, "scope_key": { "title": "Stable key agent definitions reference", "type": "string" }, "synonyms": { "title": "Term→canonical hints + sample values (JSON)" }, "title": { "title": "Display name", "type": "string" } }, "required": [ "scope_key", "title" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.grounding_scope" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.define_grounding_scope:apply" ] } ], "summary": "Define grounding scope", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.define_grounding_scope/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_define_grounding_scope` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.define_grounding_scope:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_define_grounding_scope", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "instructions": { "title": "Curator instructions injected into the retrieval context", "type": "string" }, "metric_refs": { "title": "MetricDef names in scope (JSON array)" }, "object_type_refs": { "title": "Object-type api-names in scope (JSON array)" }, "scope_key": { "title": "Stable key agent definitions reference", "type": "string" }, "synonyms": { "title": "Term→canonical hints + sample values (JSON)" }, "title": { "title": "Display name", "type": "string" } }, "required": [ "scope_key", "title" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.grounding_scope" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Define grounding scope (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.define_grounding_scope/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_define_grounding_scope`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_define_grounding_scope", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "instructions": { "title": "Curator instructions injected into the retrieval context", "type": "string" }, "metric_refs": { "title": "MetricDef names in scope (JSON array)" }, "object_type_refs": { "title": "Object-type api-names in scope (JSON array)" }, "scope_key": { "title": "Stable key agent definitions reference", "type": "string" }, "synonyms": { "title": "Term→canonical hints + sample values (JSON)" }, "title": { "title": "Display name", "type": "string" } }, "required": [ "scope_key", "title" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Define grounding scope (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.define_grounding_scope/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_define_grounding_scope` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.define_grounding_scope:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_define_grounding_scope", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "instructions": { "title": "Curator instructions injected into the retrieval context", "type": "string" }, "metric_refs": { "title": "MetricDef names in scope (JSON array)" }, "object_type_refs": { "title": "Object-type api-names in scope (JSON array)" }, "scope_key": { "title": "Stable key agent definitions reference", "type": "string" }, "synonyms": { "title": "Term→canonical hints + sample values (JSON)" }, "title": { "title": "Display name", "type": "string" } }, "required": [ "scope_key", "title" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Define grounding scope (rollup delta)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.define_maintenance_plan/apply": { "post": { "description": "Put a room on a preventive-maintenance cadence: the work order to raise (title, category, severity, description), every `interval_days`, `fixed` to the calendar or `floating` from the last completion (UpKeep's and Maximo's switch), first due on `first_due_on`. The plan starts `scheduled`; the automation lane raises its order when the date comes. Emits `maintenance_plan.defined`.\n\nEffects: create hospitality.maintenance_plan; link hospitality.link.maintenance_plan_for_room; link hospitality.link.maintenance_plan_for_asset.", "operationId": "apply_hospitality_action_define_maintenance_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "title": "The equipment the plan looks after (same house, not retired); each raised order is for it too, and retiring it retires the plan", "type": "string", "x-aerandil-references": "hospitality.asset" }, "cadence": { "enum": [ "fixed", "floating" ], "title": "fixed (to the calendar) or floating (from the last completion)", "type": "string" }, "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "Work order category", "type": "string" }, "description": { "title": "Detail carried onto each raised work order", "type": "string" }, "first_due_on": { "format": "date", "title": "The first due date", "type": "string" }, "interval_days": { "title": "Days between occurrences (1 to 3650)", "type": "integer" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "title": "Work order severity", "type": "string" }, "title": { "title": "What each raised work order says to do", "type": "string" } }, "required": [ "title", "category", "severity", "cadence", "interval_days", "first_due_on" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.maintenance_plan_for_room", "hospitality.link.maintenance_plan_for_asset" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.maintenance_plan" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.define_maintenance_plan:apply" ] } ], "summary": "Define maintenance plan", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.define_maintenance_plan/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_define_maintenance_plan` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.define_maintenance_plan:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_define_maintenance_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "title": "The equipment the plan looks after (same house, not retired); each raised order is for it too, and retiring it retires the plan", "type": "string", "x-aerandil-references": "hospitality.asset" }, "cadence": { "enum": [ "fixed", "floating" ], "title": "fixed (to the calendar) or floating (from the last completion)", "type": "string" }, "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "Work order category", "type": "string" }, "description": { "title": "Detail carried onto each raised work order", "type": "string" }, "first_due_on": { "format": "date", "title": "The first due date", "type": "string" }, "interval_days": { "title": "Days between occurrences (1 to 3650)", "type": "integer" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "title": "Work order severity", "type": "string" }, "title": { "title": "What each raised work order says to do", "type": "string" } }, "required": [ "title", "category", "severity", "cadence", "interval_days", "first_due_on" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.maintenance_plan_for_room", "hospitality.link.maintenance_plan_for_asset" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.maintenance_plan" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Define maintenance plan (dry-run)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.define_maintenance_plan/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_define_maintenance_plan`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_define_maintenance_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "title": "The equipment the plan looks after (same house, not retired); each raised order is for it too, and retiring it retires the plan", "type": "string", "x-aerandil-references": "hospitality.asset" }, "cadence": { "enum": [ "fixed", "floating" ], "title": "fixed (to the calendar) or floating (from the last completion)", "type": "string" }, "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "Work order category", "type": "string" }, "description": { "title": "Detail carried onto each raised work order", "type": "string" }, "first_due_on": { "format": "date", "title": "The first due date", "type": "string" }, "interval_days": { "title": "Days between occurrences (1 to 3650)", "type": "integer" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "title": "Work order severity", "type": "string" }, "title": { "title": "What each raised work order says to do", "type": "string" } }, "required": [ "title", "category", "severity", "cadence", "interval_days", "first_due_on" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Define maintenance plan (dry-run)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.define_maintenance_plan/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_define_maintenance_plan` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.define_maintenance_plan:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_define_maintenance_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "asset_id": { "format": "uuid", "title": "The equipment the plan looks after (same house, not retired); each raised order is for it too, and retiring it retires the plan", "type": "string", "x-aerandil-references": "hospitality.asset" }, "cadence": { "enum": [ "fixed", "floating" ], "title": "fixed (to the calendar) or floating (from the last completion)", "type": "string" }, "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "Work order category", "type": "string" }, "description": { "title": "Detail carried onto each raised work order", "type": "string" }, "first_due_on": { "format": "date", "title": "The first due date", "type": "string" }, "interval_days": { "title": "Days between occurrences (1 to 3650)", "type": "integer" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "title": "Work order severity", "type": "string" }, "title": { "title": "What each raised work order says to do", "type": "string" } }, "required": [ "title", "category", "severity", "cadence", "interval_days", "first_due_on" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Define maintenance plan (rollup delta)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.define_material/apply": { "post": { "description": "Put a part or a product in a catalogue under its code — a brand's (brand_id, shared by its houses) or one house's (property_id); exactly one. Defining a code the catalogue already holds re-states it in place (details replaced, an unstated description cleared), so the call is replay-safe and is also how a material is corrected; an identical re-statement changes nothing. The price is kept when a re-statement leaves sale_price out, and cleared by an explicit null (2026-10-17). A retired code refuses. The unit is fixed once any store holds the material. A minibar product needs a sale_price for a minibar task to charge it. The catalogue is kept by family (2026-10-17): an engineer's session defines and re-states spare parts and consumables only, a housekeeping supervisor's every other family — held to the family the code had and the one it is given (403); the desk and agents are held to none.\n\nEffects: create hospitality.material; modify hospitality.material; link hospitality.link.material_at_brand; link hospitality.link.material_at_property.", "operationId": "apply_hospitality_action_define_material", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "brand_id": { "format": "uuid", "title": "The brand's catalogue (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.brand" }, "code": { "title": "The catalogue's code for it", "type": "string" }, "description": { "title": "Notes on it", "type": "string" }, "family": { "enum": [ "spare_part", "consumable", "amenity", "linen", "minibar_product", "laundry_item", "cleaning_product", "other" ], "title": "What kind of thing it is", "type": "string" }, "name": { "title": "What it is, in words", "type": "string" }, "property_id": { "format": "uuid", "title": "One house's catalogue (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.property" }, "sale_price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "What one unit sells for (a minibar product's charge per unit)", "type": "object" }, "unit": { "enum": [ "each", "pack", "pair", "roll", "kg", "l", "m" ], "title": "The unit it is counted in", "type": "string" } }, "required": [ "code", "name", "family", "unit" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.material_at_brand", "hospitality.link.material_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.material" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.define_material:apply" ] } ], "summary": "Define material", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.define_material/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_define_material` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.define_material:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_define_material", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "brand_id": { "format": "uuid", "title": "The brand's catalogue (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.brand" }, "code": { "title": "The catalogue's code for it", "type": "string" }, "description": { "title": "Notes on it", "type": "string" }, "family": { "enum": [ "spare_part", "consumable", "amenity", "linen", "minibar_product", "laundry_item", "cleaning_product", "other" ], "title": "What kind of thing it is", "type": "string" }, "name": { "title": "What it is, in words", "type": "string" }, "property_id": { "format": "uuid", "title": "One house's catalogue (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.property" }, "sale_price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "What one unit sells for (a minibar product's charge per unit)", "type": "object" }, "unit": { "enum": [ "each", "pack", "pair", "roll", "kg", "l", "m" ], "title": "The unit it is counted in", "type": "string" } }, "required": [ "code", "name", "family", "unit" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.material_at_brand", "hospitality.link.material_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.material" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Define material (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.define_material/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_define_material`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_define_material", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "brand_id": { "format": "uuid", "title": "The brand's catalogue (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.brand" }, "code": { "title": "The catalogue's code for it", "type": "string" }, "description": { "title": "Notes on it", "type": "string" }, "family": { "enum": [ "spare_part", "consumable", "amenity", "linen", "minibar_product", "laundry_item", "cleaning_product", "other" ], "title": "What kind of thing it is", "type": "string" }, "name": { "title": "What it is, in words", "type": "string" }, "property_id": { "format": "uuid", "title": "One house's catalogue (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.property" }, "sale_price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "What one unit sells for (a minibar product's charge per unit)", "type": "object" }, "unit": { "enum": [ "each", "pack", "pair", "roll", "kg", "l", "m" ], "title": "The unit it is counted in", "type": "string" } }, "required": [ "code", "name", "family", "unit" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Define material (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.define_material/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_define_material` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.define_material:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_define_material", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "brand_id": { "format": "uuid", "title": "The brand's catalogue (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.brand" }, "code": { "title": "The catalogue's code for it", "type": "string" }, "description": { "title": "Notes on it", "type": "string" }, "family": { "enum": [ "spare_part", "consumable", "amenity", "linen", "minibar_product", "laundry_item", "cleaning_product", "other" ], "title": "What kind of thing it is", "type": "string" }, "name": { "title": "What it is, in words", "type": "string" }, "property_id": { "format": "uuid", "title": "One house's catalogue (exactly one of brand_id / property_id)", "type": "string", "x-aerandil-references": "hospitality.property" }, "sale_price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "What one unit sells for (a minibar product's charge per unit)", "type": "object" }, "unit": { "enum": [ "each", "pack", "pair", "roll", "kg", "l", "m" ], "title": "The unit it is counted in", "type": "string" } }, "required": [ "code", "name", "family", "unit" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Define material (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.define_metric/apply": { "post": { "description": "Create version 1 of a governed metric definition in `draft`. `name` is the stable snake_case identifier (matching a conformed registry metric when one exists — certifying that executable definition — or naming operator vocabulary the platform does not yet compute). The handler validates every referenced object type and field against the Registry; a definition cannot reference a field that doesn't exist. One live row per name — evolving an existing definition is `revise_metric`. Emits `metric.defined`.\n\nEffects: create hospitality.metric_definition.", "operationId": "apply_hospitality_action_define_metric", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "description": { "title": "Disambiguating prose — the definition operators sign off on", "type": "string" }, "display_name": { "title": "Display name", "type": "string" }, "formula_expression": { "title": "Canonical formula expression (governed prose, not executed)", "type": "string" }, "grain": { "enum": [ "property_day", "property_month", "venue_day", "venue_month", "outlet_day", "brand_month", "portfolio_month", "tenant_month" ], "title": "Organisational-unit × period grain", "type": "string" }, "name": { "title": "Stable metric name (snake_case)", "type": "string" }, "owner": { "title": "Accountable team / principal for the definition", "type": "string" }, "referenced_fields": { "items": { "type": "string" }, "title": "Registered `.` fields the formula reads", "type": "array" }, "referenced_object_types": { "items": { "type": "string" }, "title": "Registered object-type names the formula reads", "type": "array" }, "unit": { "enum": [ "money", "ratio", "percent", "count", "hours", "native_unit" ], "title": "Unit the metric's value carries", "type": "string" } }, "required": [ "display_name", "description", "grain", "unit", "formula_expression", "referenced_object_types", "referenced_fields", "owner", "name" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.metric_definition" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.define_metric:apply" ] } ], "summary": "Define metric", "tags": [ "catalogue" ] } }, "/v1/actions/hospitality.action.define_metric/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_define_metric` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.define_metric:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_define_metric", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "description": { "title": "Disambiguating prose — the definition operators sign off on", "type": "string" }, "display_name": { "title": "Display name", "type": "string" }, "formula_expression": { "title": "Canonical formula expression (governed prose, not executed)", "type": "string" }, "grain": { "enum": [ "property_day", "property_month", "venue_day", "venue_month", "outlet_day", "brand_month", "portfolio_month", "tenant_month" ], "title": "Organisational-unit × period grain", "type": "string" }, "name": { "title": "Stable metric name (snake_case)", "type": "string" }, "owner": { "title": "Accountable team / principal for the definition", "type": "string" }, "referenced_fields": { "items": { "type": "string" }, "title": "Registered `.` fields the formula reads", "type": "array" }, "referenced_object_types": { "items": { "type": "string" }, "title": "Registered object-type names the formula reads", "type": "array" }, "unit": { "enum": [ "money", "ratio", "percent", "count", "hours", "native_unit" ], "title": "Unit the metric's value carries", "type": "string" } }, "required": [ "display_name", "description", "grain", "unit", "formula_expression", "referenced_object_types", "referenced_fields", "owner", "name" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.metric_definition" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Define metric (dry-run)", "tags": [ "catalogue" ] } }, "/v1/actions/hospitality.action.define_metric/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_define_metric`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_define_metric", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "description": { "title": "Disambiguating prose — the definition operators sign off on", "type": "string" }, "display_name": { "title": "Display name", "type": "string" }, "formula_expression": { "title": "Canonical formula expression (governed prose, not executed)", "type": "string" }, "grain": { "enum": [ "property_day", "property_month", "venue_day", "venue_month", "outlet_day", "brand_month", "portfolio_month", "tenant_month" ], "title": "Organisational-unit × period grain", "type": "string" }, "name": { "title": "Stable metric name (snake_case)", "type": "string" }, "owner": { "title": "Accountable team / principal for the definition", "type": "string" }, "referenced_fields": { "items": { "type": "string" }, "title": "Registered `.` fields the formula reads", "type": "array" }, "referenced_object_types": { "items": { "type": "string" }, "title": "Registered object-type names the formula reads", "type": "array" }, "unit": { "enum": [ "money", "ratio", "percent", "count", "hours", "native_unit" ], "title": "Unit the metric's value carries", "type": "string" } }, "required": [ "display_name", "description", "grain", "unit", "formula_expression", "referenced_object_types", "referenced_fields", "owner", "name" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Define metric (dry-run)", "tags": [ "catalogue" ] } }, "/v1/actions/hospitality.action.define_metric/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_define_metric` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.define_metric:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_define_metric", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "description": { "title": "Disambiguating prose — the definition operators sign off on", "type": "string" }, "display_name": { "title": "Display name", "type": "string" }, "formula_expression": { "title": "Canonical formula expression (governed prose, not executed)", "type": "string" }, "grain": { "enum": [ "property_day", "property_month", "venue_day", "venue_month", "outlet_day", "brand_month", "portfolio_month", "tenant_month" ], "title": "Organisational-unit × period grain", "type": "string" }, "name": { "title": "Stable metric name (snake_case)", "type": "string" }, "owner": { "title": "Accountable team / principal for the definition", "type": "string" }, "referenced_fields": { "items": { "type": "string" }, "title": "Registered `.` fields the formula reads", "type": "array" }, "referenced_object_types": { "items": { "type": "string" }, "title": "Registered object-type names the formula reads", "type": "array" }, "unit": { "enum": [ "money", "ratio", "percent", "count", "hours", "native_unit" ], "title": "Unit the metric's value carries", "type": "string" } }, "required": [ "display_name", "description", "grain", "unit", "formula_expression", "referenced_object_types", "referenced_fields", "owner", "name" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Define metric (rollup delta)", "tags": [ "catalogue" ] } }, "/v1/actions/hospitality.action.define_round_template/apply": { "post": { "description": "Define a house's planned walk — hubOS's revision structure: its `name`, `family` (corrective, preventive, technical_legal, inspection_legal), cadence (`fixed` to the calendar or `floating` from the last completion, every `interval_days` — the maintenance plan's vocabulary) and the `checkpoints` in walking order. Each checkpoint has a unique `position`, a `kind` — `room` or `asset` with `ref_id` naming one of this house's rooms or (unretired) assets, or `general` with a `label` and no `ref_id` — and its `items`, each a unique `code`, a `label` and a `kind` (`check`; `reading` with an optional `unit` and optional limits `min` / `max`, inclusive, which judge a reading the walker leaves unjudged; `text`; `photo`, answered by a photo on the checkpoint's result; `section`, a heading never answered — a checkpoint needs at least one item that is not a heading). Replay-safe by its business key, house × name: the same name again revises the active template's family, cadence, description and checkpoints in place (an identical repeat writes nothing; a round already under way keeps the checkpoints it started with). The template carries its `revision` — 1 when defined, one more each time a re-definition moves its checkpoints (words and schedule leave it) — which a start may name. `next_due_on` is the date the next round is due — required the first time; on a revision, absent keeps the schedule. After `retire_round_template` the name mints a new template. Emits `round_template.defined`.\n\nEffects: create hospitality.round_template; modify hospitality.round_template; link hospitality.link.round_template_at_property.", "operationId": "apply_hospitality_action_define_round_template", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cadence": { "enum": [ "fixed", "floating" ], "title": "fixed (to the calendar) or floating (from the last completion)", "type": "string" }, "checkpoints": { "items": { "properties": { "items": { "items": { "properties": { "code": { "type": "string" }, "kind": { "enum": [ "check", "reading", "text", "photo", "section" ], "type": "string" }, "label": { "type": "string" }, "max": { "format": "decimal", "type": "string" }, "min": { "format": "decimal", "type": "string" }, "unit": { "type": "string" } }, "required": [ "code", "label", "kind" ], "type": "object" }, "type": "array" }, "kind": { "enum": [ "room", "asset", "general" ], "type": "string" }, "label": { "type": "string" }, "position": { "type": "integer" }, "ref_id": { "type": "string" } }, "required": [ "position", "kind", "items" ], "type": "object" }, "title": "Round checkpoints", "type": "array" }, "description": { "title": "What the walk is for, in words", "type": "string" }, "family": { "enum": [ "corrective", "preventive", "technical_legal", "inspection_legal" ], "title": "corrective, preventive, technical_legal or inspection_legal", "type": "string" }, "interval_days": { "title": "Days between rounds (1 to 3650)", "type": "integer" }, "name": { "title": "What the walk is called (unique among the house's active templates)", "type": "string" }, "next_due_on": { "format": "date", "title": "The date the next round is due (required the first time; absent on a revision keeps the schedule)", "type": "string" } }, "required": [ "name", "family", "cadence", "interval_days", "checkpoints" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.round_template_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.round_template" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.define_round_template:apply" ] } ], "summary": "Define round template", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.define_round_template/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_define_round_template` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.define_round_template:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_define_round_template", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cadence": { "enum": [ "fixed", "floating" ], "title": "fixed (to the calendar) or floating (from the last completion)", "type": "string" }, "checkpoints": { "items": { "properties": { "items": { "items": { "properties": { "code": { "type": "string" }, "kind": { "enum": [ "check", "reading", "text", "photo", "section" ], "type": "string" }, "label": { "type": "string" }, "max": { "format": "decimal", "type": "string" }, "min": { "format": "decimal", "type": "string" }, "unit": { "type": "string" } }, "required": [ "code", "label", "kind" ], "type": "object" }, "type": "array" }, "kind": { "enum": [ "room", "asset", "general" ], "type": "string" }, "label": { "type": "string" }, "position": { "type": "integer" }, "ref_id": { "type": "string" } }, "required": [ "position", "kind", "items" ], "type": "object" }, "title": "Round checkpoints", "type": "array" }, "description": { "title": "What the walk is for, in words", "type": "string" }, "family": { "enum": [ "corrective", "preventive", "technical_legal", "inspection_legal" ], "title": "corrective, preventive, technical_legal or inspection_legal", "type": "string" }, "interval_days": { "title": "Days between rounds (1 to 3650)", "type": "integer" }, "name": { "title": "What the walk is called (unique among the house's active templates)", "type": "string" }, "next_due_on": { "format": "date", "title": "The date the next round is due (required the first time; absent on a revision keeps the schedule)", "type": "string" } }, "required": [ "name", "family", "cadence", "interval_days", "checkpoints" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.round_template_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.round_template" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Define round template (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.define_round_template/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_define_round_template`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_define_round_template", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cadence": { "enum": [ "fixed", "floating" ], "title": "fixed (to the calendar) or floating (from the last completion)", "type": "string" }, "checkpoints": { "items": { "properties": { "items": { "items": { "properties": { "code": { "type": "string" }, "kind": { "enum": [ "check", "reading", "text", "photo", "section" ], "type": "string" }, "label": { "type": "string" }, "max": { "format": "decimal", "type": "string" }, "min": { "format": "decimal", "type": "string" }, "unit": { "type": "string" } }, "required": [ "code", "label", "kind" ], "type": "object" }, "type": "array" }, "kind": { "enum": [ "room", "asset", "general" ], "type": "string" }, "label": { "type": "string" }, "position": { "type": "integer" }, "ref_id": { "type": "string" } }, "required": [ "position", "kind", "items" ], "type": "object" }, "title": "Round checkpoints", "type": "array" }, "description": { "title": "What the walk is for, in words", "type": "string" }, "family": { "enum": [ "corrective", "preventive", "technical_legal", "inspection_legal" ], "title": "corrective, preventive, technical_legal or inspection_legal", "type": "string" }, "interval_days": { "title": "Days between rounds (1 to 3650)", "type": "integer" }, "name": { "title": "What the walk is called (unique among the house's active templates)", "type": "string" }, "next_due_on": { "format": "date", "title": "The date the next round is due (required the first time; absent on a revision keeps the schedule)", "type": "string" } }, "required": [ "name", "family", "cadence", "interval_days", "checkpoints" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Define round template (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.define_round_template/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_define_round_template` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.define_round_template:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_define_round_template", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cadence": { "enum": [ "fixed", "floating" ], "title": "fixed (to the calendar) or floating (from the last completion)", "type": "string" }, "checkpoints": { "items": { "properties": { "items": { "items": { "properties": { "code": { "type": "string" }, "kind": { "enum": [ "check", "reading", "text", "photo", "section" ], "type": "string" }, "label": { "type": "string" }, "max": { "format": "decimal", "type": "string" }, "min": { "format": "decimal", "type": "string" }, "unit": { "type": "string" } }, "required": [ "code", "label", "kind" ], "type": "object" }, "type": "array" }, "kind": { "enum": [ "room", "asset", "general" ], "type": "string" }, "label": { "type": "string" }, "position": { "type": "integer" }, "ref_id": { "type": "string" } }, "required": [ "position", "kind", "items" ], "type": "object" }, "title": "Round checkpoints", "type": "array" }, "description": { "title": "What the walk is for, in words", "type": "string" }, "family": { "enum": [ "corrective", "preventive", "technical_legal", "inspection_legal" ], "title": "corrective, preventive, technical_legal or inspection_legal", "type": "string" }, "interval_days": { "title": "Days between rounds (1 to 3650)", "type": "integer" }, "name": { "title": "What the walk is called (unique among the house's active templates)", "type": "string" }, "next_due_on": { "format": "date", "title": "The date the next round is due (required the first time; absent on a revision keeps the schedule)", "type": "string" } }, "required": [ "name", "family", "cadence", "interval_days", "checkpoints" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Define round template (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.define_stock_store/apply": { "post": { "description": "Define one of the house's stock stores under its code — the stores room, a floor cupboard, the minibar cart, a room's minibar (room_minibar, which names its room_id; one per room), the laundry, the workshop. Defining a code the house already holds re-states the store in place, so the call is replay-safe; an identical re-statement changes nothing. is_default makes it the house's store of its kind that work draws from when it names none (a minibar task in a room with no minibar of its own, a laundry task, a fault's material line) — the previous default of the kind stops being one. allow_negative lets its stock go below zero (an uncounted store); it cannot be switched off while a level is negative. The store is linked to its house (stock_store_at_property); re-stating a store defined before that edge existed writes it. A store is kept by the role whose store it is (2026-10-17): an engineer's session keeps the workshop only, a housekeeping supervisor's any store but a workshop — held to the kind the code had and the kind it is given, so neither re-kinds, defaults or loosens the other's store (403); the desk and agents are held to none.\n\nEffects: create hospitality.stock_store; modify hospitality.stock_store; link hospitality.link.stock_store_in_room; unlink hospitality.link.stock_store_in_room; link hospitality.link.stock_store_at_property.", "operationId": "apply_hospitality_action_define_stock_store", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allow_negative": { "title": "Let its stock go below zero (defaults to false)", "type": "boolean" }, "code": { "title": "The house's code for the store", "type": "string" }, "is_default": { "title": "Make it the house's store of its kind that work draws from", "type": "boolean" }, "kind": { "enum": [ "main_store", "floor_store", "minibar_cart", "room_minibar", "laundry", "workshop" ], "title": "What kind of store it is", "type": "string" }, "name": { "title": "The store in words", "type": "string" }, "room_id": { "format": "uuid", "title": "The room whose minibar it is (room_minibar only, and required there)", "type": "string", "x-aerandil-references": "hospitality.room" } }, "required": [ "code", "name", "kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.stock_store_in_room", "hospitality.link.stock_store_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.stock_store" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.define_stock_store:apply" ] } ], "summary": "Define stock store", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.define_stock_store/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_define_stock_store` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.define_stock_store:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_define_stock_store", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allow_negative": { "title": "Let its stock go below zero (defaults to false)", "type": "boolean" }, "code": { "title": "The house's code for the store", "type": "string" }, "is_default": { "title": "Make it the house's store of its kind that work draws from", "type": "boolean" }, "kind": { "enum": [ "main_store", "floor_store", "minibar_cart", "room_minibar", "laundry", "workshop" ], "title": "What kind of store it is", "type": "string" }, "name": { "title": "The store in words", "type": "string" }, "room_id": { "format": "uuid", "title": "The room whose minibar it is (room_minibar only, and required there)", "type": "string", "x-aerandil-references": "hospitality.room" } }, "required": [ "code", "name", "kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.stock_store_in_room", "hospitality.link.stock_store_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.stock_store" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Define stock store (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.define_stock_store/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_define_stock_store`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_define_stock_store", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allow_negative": { "title": "Let its stock go below zero (defaults to false)", "type": "boolean" }, "code": { "title": "The house's code for the store", "type": "string" }, "is_default": { "title": "Make it the house's store of its kind that work draws from", "type": "boolean" }, "kind": { "enum": [ "main_store", "floor_store", "minibar_cart", "room_minibar", "laundry", "workshop" ], "title": "What kind of store it is", "type": "string" }, "name": { "title": "The store in words", "type": "string" }, "room_id": { "format": "uuid", "title": "The room whose minibar it is (room_minibar only, and required there)", "type": "string", "x-aerandil-references": "hospitality.room" } }, "required": [ "code", "name", "kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Define stock store (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.define_stock_store/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_define_stock_store` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.define_stock_store:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_define_stock_store", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allow_negative": { "title": "Let its stock go below zero (defaults to false)", "type": "boolean" }, "code": { "title": "The house's code for the store", "type": "string" }, "is_default": { "title": "Make it the house's store of its kind that work draws from", "type": "boolean" }, "kind": { "enum": [ "main_store", "floor_store", "minibar_cart", "room_minibar", "laundry", "workshop" ], "title": "What kind of store it is", "type": "string" }, "name": { "title": "The store in words", "type": "string" }, "room_id": { "format": "uuid", "title": "The room whose minibar it is (room_minibar only, and required there)", "type": "string", "x-aerandil-references": "hospitality.room" } }, "required": [ "code", "name", "kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Define stock store (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.define_worker_group/apply": { "post": { "description": "Define a named group of staff at the target property that work can be assigned to — the third-floor runners, the public-areas team, the night maintenance crew (hubOS's workers groups). `department` says whose work it takes: a housekeeping task goes to a housekeeping, public_areas or other group, a work order to a maintenance or other one. `floors`, when given, are the floors it covers — runners by floor are a group of runners naming its floors, and work in a room or area on another floor is refused to it, as is work in a room or area that states no floor. Upsert by name: the same name again restates the group in place (an identical restatement writes nothing; absent `floors` clears them), and a retired group defined again comes back active. A restatement releases the group's open work it no longer covers — on a floor it no longer names, or of a kind its department no longer takes — back to the open board, unassigned, as `retire_worker_group` does. Two first definitions of one name queue on a per-house lock, so the second restates the first. Members are `set_worker_group_members`'. Emits `worker_group.defined`, naming the work it released.\n\nEffects: create hospitality.worker_group; modify hospitality.worker_group; unlink hospitality.link.housekeeping_task_assigned_to_group; unlink hospitality.link.work_order_assigned_to_group; modify hospitality.housekeeping_task; modify hospitality.work_order.", "operationId": "apply_hospitality_action_define_worker_group", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "department": { "enum": [ "housekeeping", "maintenance", "public_areas", "other" ], "title": "Whose work the group takes", "type": "string" }, "floors": { "items": { "type": "string" }, "title": "The floors the group covers, in the rooms' own words (absent: every floor)", "type": "array" }, "name": { "title": "What the house calls the group (trimmed; unique in the house)", "type": "string" } }, "required": [ "name", "department" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.housekeeping_task_assigned_to_group", "hospitality.link.work_order_assigned_to_group" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.worker_group", "hospitality.housekeeping_task", "hospitality.work_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.define_worker_group:apply" ] } ], "summary": "Define worker group", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.define_worker_group/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_define_worker_group` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.define_worker_group:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_define_worker_group", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "department": { "enum": [ "housekeeping", "maintenance", "public_areas", "other" ], "title": "Whose work the group takes", "type": "string" }, "floors": { "items": { "type": "string" }, "title": "The floors the group covers, in the rooms' own words (absent: every floor)", "type": "array" }, "name": { "title": "What the house calls the group (trimmed; unique in the house)", "type": "string" } }, "required": [ "name", "department" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.housekeeping_task_assigned_to_group", "hospitality.link.work_order_assigned_to_group" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.worker_group", "hospitality.housekeeping_task", "hospitality.work_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Define worker group (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.define_worker_group/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_define_worker_group`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_define_worker_group", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "department": { "enum": [ "housekeeping", "maintenance", "public_areas", "other" ], "title": "Whose work the group takes", "type": "string" }, "floors": { "items": { "type": "string" }, "title": "The floors the group covers, in the rooms' own words (absent: every floor)", "type": "array" }, "name": { "title": "What the house calls the group (trimmed; unique in the house)", "type": "string" } }, "required": [ "name", "department" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Define worker group (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.define_worker_group/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_define_worker_group` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.define_worker_group:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_define_worker_group", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "department": { "enum": [ "housekeeping", "maintenance", "public_areas", "other" ], "title": "Whose work the group takes", "type": "string" }, "floors": { "items": { "type": "string" }, "title": "The floors the group covers, in the rooms' own words (absent: every floor)", "type": "array" }, "name": { "title": "What the house calls the group (trimmed; unique in the house)", "type": "string" } }, "required": [ "name", "department" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Define worker group (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.delist_retail_product/apply": { "post": { "description": "End all active retail_product_available_at_* placements for the target product as of `delisted_at`. Portfolio-wide delisting verb distinct from per-listing effective_to edits.\n\nEffects: unlink hospitality.link.retail_product_available_at_property; unlink hospitality.link.retail_product_available_at_venue.", "operationId": "apply_hospitality_action_delist_retail_product", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "delisted_at": { "format": "date-time", "title": "Delisting timestamp", "type": "string" } }, "required": [ "delisted_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.retail_product" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.retail_product_available_at_property", "hospitality.link.retail_product_available_at_venue" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.delist_retail_product:apply" ] } ], "summary": "Delist retail product", "tags": [ "brand_venue" ] } }, "/v1/actions/hospitality.action.delist_retail_product/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_delist_retail_product` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.delist_retail_product:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_delist_retail_product", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "delisted_at": { "format": "date-time", "title": "Delisting timestamp", "type": "string" } }, "required": [ "delisted_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.retail_product" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.retail_product_available_at_property", "hospitality.link.retail_product_available_at_venue" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Delist retail product (dry-run)", "tags": [ "brand_venue" ] } }, "/v1/actions/hospitality.action.delist_retail_product/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_delist_retail_product`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_delist_retail_product", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "delisted_at": { "format": "date-time", "title": "Delisting timestamp", "type": "string" } }, "required": [ "delisted_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.retail_product" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Delist retail product (dry-run)", "tags": [ "brand_venue" ] } }, "/v1/actions/hospitality.action.delist_retail_product/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_delist_retail_product` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.delist_retail_product:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_delist_retail_product", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "delisted_at": { "format": "date-time", "title": "Delisting timestamp", "type": "string" } }, "required": [ "delisted_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.retail_product" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Delist retail product (rollup delta)", "tags": [ "brand_venue" ] } }, "/v1/actions/hospitality.action.deliver_room_service/apply": { "post": { "description": "An in-room dining order reaches the room: the target room-service check's `delivery_status` goes `dispatched` → `delivered`, stamping `delivered_at` — what the board's lateness stops counting at. Only from `dispatched`. Emits `fnb.room_service_delivered`.\n\nEffects: modify hospitality.guest_check.", "operationId": "apply_hospitality_action_deliver_room_service", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.guest_check" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.deliver_room_service:apply" ] } ], "summary": "Deliver room service", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.deliver_room_service/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_deliver_room_service` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.deliver_room_service:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_deliver_room_service", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.guest_check" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Deliver room service (dry-run)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.deliver_room_service/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_deliver_room_service`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_deliver_room_service", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Deliver room service (dry-run)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.deliver_room_service/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_deliver_room_service` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.deliver_room_service:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_deliver_room_service", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Deliver room service (rollup delta)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.deprecate_agent_registry_entry/apply": { "post": { "description": "Mark a registry entry `deprecated` — new installations are refused (`agent_registry_approved_before_install`), but existing installations keep running so operators migrate on their own schedule (npm-deprecate semantics: a warning, not a kill switch — that is `block_agent_registry_entry`). Emits `agent_registry_entry.deprecated`.\n\nEffects: modify hospitality.agent_registry_entry.", "operationId": "apply_hospitality_action_deprecate_agent_registry_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the entry is deprecated (migration pointer)", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_registry_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.agent_registry_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.deprecate_agent_registry_entry:apply" ] } ], "summary": "Deprecate agent registry entry", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.deprecate_agent_registry_entry/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_deprecate_agent_registry_entry` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.deprecate_agent_registry_entry:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_deprecate_agent_registry_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the entry is deprecated (migration pointer)", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_registry_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.agent_registry_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Deprecate agent registry entry (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.deprecate_agent_registry_entry/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_deprecate_agent_registry_entry`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_deprecate_agent_registry_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the entry is deprecated (migration pointer)", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_registry_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Deprecate agent registry entry (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.deprecate_agent_registry_entry/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_deprecate_agent_registry_entry` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.deprecate_agent_registry_entry:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_deprecate_agent_registry_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the entry is deprecated (migration pointer)", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_registry_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Deprecate agent registry entry (rollup delta)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.deprecate_federated_program/apply": { "post": { "description": "Stop new definitions / runs while preserving historical outputs. Transitions program status to `deprecated` or `retired`. Existing published outputs remain available unless separately quarantined (proposal §8.2).\n\nEffects: modify hospitality.federated_intelligence_program.", "operationId": "apply_hospitality_action_deprecate_federated_program", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "deprecation_reason": { "title": "Required text reason", "type": "string" }, "effective_at": { "format": "date-time", "title": "Defaults to now()", "type": "string" }, "new_status": { "enum": [ "deprecated", "retired" ], "title": "deprecated | retired", "type": "string" } }, "required": [ "deprecation_reason", "new_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_intelligence_program" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.federated_intelligence_program" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.deprecate_federated_program:apply" ] } ], "summary": "Deprecate federated intelligence program", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.deprecate_federated_program/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_deprecate_federated_program` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.deprecate_federated_program:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_deprecate_federated_program", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "deprecation_reason": { "title": "Required text reason", "type": "string" }, "effective_at": { "format": "date-time", "title": "Defaults to now()", "type": "string" }, "new_status": { "enum": [ "deprecated", "retired" ], "title": "deprecated | retired", "type": "string" } }, "required": [ "deprecation_reason", "new_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_intelligence_program" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.federated_intelligence_program" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Deprecate federated intelligence program (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.deprecate_federated_program/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_deprecate_federated_program`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_deprecate_federated_program", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "deprecation_reason": { "title": "Required text reason", "type": "string" }, "effective_at": { "format": "date-time", "title": "Defaults to now()", "type": "string" }, "new_status": { "enum": [ "deprecated", "retired" ], "title": "deprecated | retired", "type": "string" } }, "required": [ "deprecation_reason", "new_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_intelligence_program" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Deprecate federated intelligence program (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.deprecate_federated_program/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_deprecate_federated_program` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.deprecate_federated_program:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_deprecate_federated_program", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "deprecation_reason": { "title": "Required text reason", "type": "string" }, "effective_at": { "format": "date-time", "title": "Defaults to now()", "type": "string" }, "new_status": { "enum": [ "deprecated", "retired" ], "title": "deprecated | retired", "type": "string" } }, "required": [ "deprecation_reason", "new_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_intelligence_program" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Deprecate federated intelligence program (rollup delta)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.deprecate_metric/apply": { "post": { "description": "Retire the targeted definition version: status → `deprecated`, terminal for this version — it returns only via `revise_metric` at a strictly greater version. Idempotent on an already-deprecated version. The optional `reason` lands in the event payload for the audit trail. Emits `metric.deprecated`.\n\nEffects: modify hospitality.metric_definition.", "operationId": "apply_hospitality_action_deprecate_metric", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the definition is being deprecated", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.metric_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.metric_definition" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.deprecate_metric:apply" ] } ], "summary": "Deprecate metric", "tags": [ "catalogue" ] } }, "/v1/actions/hospitality.action.deprecate_metric/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_deprecate_metric` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.deprecate_metric:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_deprecate_metric", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the definition is being deprecated", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.metric_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.metric_definition" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Deprecate metric (dry-run)", "tags": [ "catalogue" ] } }, "/v1/actions/hospitality.action.deprecate_metric/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_deprecate_metric`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_deprecate_metric", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the definition is being deprecated", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.metric_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Deprecate metric (dry-run)", "tags": [ "catalogue" ] } }, "/v1/actions/hospitality.action.deprecate_metric/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_deprecate_metric` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.deprecate_metric:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_deprecate_metric", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the definition is being deprecated", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.metric_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Deprecate metric (rollup delta)", "tags": [ "catalogue" ] } }, "/v1/actions/hospitality.action.deprecate_workflow_definition/apply": { "post": { "description": "Prevents new runs without disturbing existing runs. Validates the target is `active` or `draft`; sets `status = deprecated` and stamps `deprecated_at`. New runs against the deprecated version are rejected by `workflow_run_requires_active_definition`; existing runs continue under their pinned `definition_hash`.\n\nEffects: modify hospitality.workflow_definition.", "operationId": "apply_hospitality_action_deprecate_workflow_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "deprecated_at": { "format": "date-time", "title": "Defaults to now()", "type": "string" }, "deprecation_reason": { "title": "Required text reason", "type": "string" }, "replacement_definition_id": { "title": "Optional pointer to a successor", "type": "string" } }, "required": [ "deprecation_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.workflow_definition" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.deprecate_workflow_definition:apply" ] } ], "summary": "Deprecate workflow definition", "tags": [ "workflows" ] } }, "/v1/actions/hospitality.action.deprecate_workflow_definition/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_deprecate_workflow_definition` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.deprecate_workflow_definition:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_deprecate_workflow_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "deprecated_at": { "format": "date-time", "title": "Defaults to now()", "type": "string" }, "deprecation_reason": { "title": "Required text reason", "type": "string" }, "replacement_definition_id": { "title": "Optional pointer to a successor", "type": "string" } }, "required": [ "deprecation_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.workflow_definition" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Deprecate workflow definition (dry-run)", "tags": [ "workflows" ] } }, "/v1/actions/hospitality.action.deprecate_workflow_definition/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_deprecate_workflow_definition`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_deprecate_workflow_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "deprecated_at": { "format": "date-time", "title": "Defaults to now()", "type": "string" }, "deprecation_reason": { "title": "Required text reason", "type": "string" }, "replacement_definition_id": { "title": "Optional pointer to a successor", "type": "string" } }, "required": [ "deprecation_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Deprecate workflow definition (dry-run)", "tags": [ "workflows" ] } }, "/v1/actions/hospitality.action.deprecate_workflow_definition/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_deprecate_workflow_definition` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.deprecate_workflow_definition:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_deprecate_workflow_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "deprecated_at": { "format": "date-time", "title": "Defaults to now()", "type": "string" }, "deprecation_reason": { "title": "Required text reason", "type": "string" }, "replacement_definition_id": { "title": "Optional pointer to a successor", "type": "string" } }, "required": [ "deprecation_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Deprecate workflow definition (rollup delta)", "tags": [ "workflows" ] } }, "/v1/actions/hospitality.action.detect_fraud_risk/apply": { "post": { "description": "Emit a typed fraud-risk assessment against a reservation (the dominant fire-target), payment, charge, person, loyalty redemption, or a folio with no booking behind it (a group master or house account taking a card hold; the folio must sit at the target property). Targets the property (container); the scoring subject is identified by subject_kind + subject_id params. Inserts a `fraud_risk_assessment` row in `suggested` state with an immutable `risk_context_snapshot` captured at issue time. Validators enforce: subject_kind/subject_id coherence, band/score coherence, recommended_action/band coherence, score and confidence bounds, reason-code contribution bounds, PCI no-PAN in snapshot. Decision lifecycle flows through apply / reject / escalate / expire.\n\nEffects: create hospitality.fraud_risk_assessment; modify hospitality.fraud_risk_assessment; link hospitality.link.fraud_assessment_for_reservation; link hospitality.link.fraud_assessment_for_person; link hospitality.link.fraud_assessment_for_charge; link hospitality.link.fraud_assessment_at_property; link hospitality.link.fraud_assessment_references_external_record; link hospitality.link.fraud_assessment_superseded_by; link hospitality.link.fraud_assessment_for_prior_triage; link hospitality.link.fraud_assessment_consulted_network.", "operationId": "apply_hospitality_action_detect_fraud_risk", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "band": { "enum": [ "low", "medium", "high", "block", "not_assessed" ], "title": "Risk band ordinal", "type": "string" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Operator-facing confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Calibrated probability [0, 1] (optional)", "type": "string" }, "coverage_guaranteed": { "title": "True when the vendor's chargeback-guarantee covers this decision", "type": "boolean" }, "coverage_terms_uri": { "title": "Pointer to the vendor's coverage terms", "type": "string" }, "expires_at": { "format": "date-time", "title": "Assessment expiry (default per fire-point — see proposal §3.1)", "type": "string" }, "external_record_ref": { "format": "uuid", "title": "Optional pointer to vendor raw payload (external_record_reference)", "type": "string", "x-aerandil-references": "hospitality.external_record_reference" }, "factors_considered": { "items": { "enum": [ "payment_signal", "identity_signal", "behavioural_signal", "device_signal", "velocity_signal", "geo_signal", "lead_time", "loyalty_account_age", "prior_chargeback_history", "prior_recovery_history", "third_party_payer_flag", "vcn_detected", "injection_history", "network_outcome", "kyc_outcome", "three_ds_outcome", "watchlist_match", "graph_signal", "fraud_network_signal", "other" ], "type": "string" }, "title": "Signals the assessment conditioned on", "type": "array" }, "feature_payload_hash": { "title": "SHA-256 of canonical input-feature JSON (chargeback-defence tamper-evidence)", "type": "string" }, "fire_point": { "enum": [ "at_booking", "at_payment", "at_check_in", "at_folio_close", "on_chargeback_attempt" ], "title": "Lifecycle moment the assessment fired at", "type": "string" }, "folio_charge_ref": { "format": "uuid", "title": "Optional charge anchor", "type": "string", "x-aerandil-references": "hospitality.charge" }, "fraud_network_signal_ref": { "format": "uuid", "title": "The Watchtower answer this assessment was scored with; its band floor binds the band", "type": "string", "x-aerandil-references": "hospitality.fraud_network_signal" }, "person_ref": { "format": "uuid", "title": "Optional denormalised person anchor", "type": "string", "x-aerandil-references": "hospitality.person" }, "policy_outcomes": { "items": { "enum": [ "psd2_sca_required", "psd2_sca_out_of_scope_moto", "psd2_sca_exempted_low_value", "psd2_sca_exempted_trusted_beneficiaries", "psd2_sca_exempted_tra", "psd2_sca_exempted_recurring", "psd2_sca_exempted_corporate_payment", "three_ds_y", "three_ds_a", "three_ds_u", "three_ds_n", "three_ds_r", "three_ds_not_attempted", "gdpr_art22_explanation_required", "pci_token_only", "pci_last4_only", "facta_red_flag_match", "fincen_8300_threshold_met", "eu_ai_act_high_risk_processing", "ccpa_admt_notice_required", "none" ], "type": "string" }, "title": "Compliance flags observed during scoring", "type": "array" }, "prior_triage_ref": { "format": "uuid", "title": "Optional cross-surface link to a prior message_triage (e.g. injection.suspected)", "type": "string", "x-aerandil-references": "hospitality.message_triage" }, "rationale_text": { "title": "Human-readable explanation", "type": "string" }, "reason_codes": { "title": "Explanation array (JSON array of {code, severity, contribution})" }, "recommended_action": { "enum": [ "approve", "review", "step_up_3ds", "step_up_kyc", "decline", "escalate" ], "title": "Recommended action class", "type": "string" }, "reservation_ref": { "format": "uuid", "title": "Optional denormalised reservation anchor", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "risk_context_snapshot": { "additionalProperties": true, "title": "Frozen context snapshot at issue time (JSON; host populates per recommended shape)", "type": "object" }, "score": { "format": "decimal", "title": "Raw numeric score on the [0, 100] scale", "type": "string" }, "score_calibrated": { "format": "decimal", "title": "Optional calibrated probability [0, 1]", "type": "string" }, "subject_id": { "title": "Id of the typed object the assessment scored", "type": "string" }, "subject_kind": { "enum": [ "reservation", "payment", "charge", "person", "loyalty_redemption", "folio" ], "title": "What kind of object the assessment scored", "type": "string" }, "triggered_rules": { "title": "Custom-rule provenance (JSON array of {rule_id, rule_version, action})" }, "vendor_id": { "title": "Vendor identity (denormalised from Principal::Agent.vendor)", "type": "string" }, "vendor_model_version": { "title": "Vendor model version when exposed", "type": "string" } }, "required": [ "subject_kind", "subject_id", "fire_point", "vendor_id", "score", "band", "recommended_action", "confidence", "factors_considered", "reason_codes", "rationale_text", "risk_context_snapshot", "policy_outcomes" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.fraud_assessment_for_reservation", "hospitality.link.fraud_assessment_for_person", "hospitality.link.fraud_assessment_for_charge", "hospitality.link.fraud_assessment_at_property", "hospitality.link.fraud_assessment_references_external_record", "hospitality.link.fraud_assessment_superseded_by", "hospitality.link.fraud_assessment_for_prior_triage", "hospitality.link.fraud_assessment_consulted_network" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.fraud_risk_assessment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.detect_fraud_risk:apply" ] } ], "summary": "Detect fraud risk", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.detect_fraud_risk/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_detect_fraud_risk` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.detect_fraud_risk:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_detect_fraud_risk", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "band": { "enum": [ "low", "medium", "high", "block", "not_assessed" ], "title": "Risk band ordinal", "type": "string" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Operator-facing confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Calibrated probability [0, 1] (optional)", "type": "string" }, "coverage_guaranteed": { "title": "True when the vendor's chargeback-guarantee covers this decision", "type": "boolean" }, "coverage_terms_uri": { "title": "Pointer to the vendor's coverage terms", "type": "string" }, "expires_at": { "format": "date-time", "title": "Assessment expiry (default per fire-point — see proposal §3.1)", "type": "string" }, "external_record_ref": { "format": "uuid", "title": "Optional pointer to vendor raw payload (external_record_reference)", "type": "string", "x-aerandil-references": "hospitality.external_record_reference" }, "factors_considered": { "items": { "enum": [ "payment_signal", "identity_signal", "behavioural_signal", "device_signal", "velocity_signal", "geo_signal", "lead_time", "loyalty_account_age", "prior_chargeback_history", "prior_recovery_history", "third_party_payer_flag", "vcn_detected", "injection_history", "network_outcome", "kyc_outcome", "three_ds_outcome", "watchlist_match", "graph_signal", "fraud_network_signal", "other" ], "type": "string" }, "title": "Signals the assessment conditioned on", "type": "array" }, "feature_payload_hash": { "title": "SHA-256 of canonical input-feature JSON (chargeback-defence tamper-evidence)", "type": "string" }, "fire_point": { "enum": [ "at_booking", "at_payment", "at_check_in", "at_folio_close", "on_chargeback_attempt" ], "title": "Lifecycle moment the assessment fired at", "type": "string" }, "folio_charge_ref": { "format": "uuid", "title": "Optional charge anchor", "type": "string", "x-aerandil-references": "hospitality.charge" }, "fraud_network_signal_ref": { "format": "uuid", "title": "The Watchtower answer this assessment was scored with; its band floor binds the band", "type": "string", "x-aerandil-references": "hospitality.fraud_network_signal" }, "person_ref": { "format": "uuid", "title": "Optional denormalised person anchor", "type": "string", "x-aerandil-references": "hospitality.person" }, "policy_outcomes": { "items": { "enum": [ "psd2_sca_required", "psd2_sca_out_of_scope_moto", "psd2_sca_exempted_low_value", "psd2_sca_exempted_trusted_beneficiaries", "psd2_sca_exempted_tra", "psd2_sca_exempted_recurring", "psd2_sca_exempted_corporate_payment", "three_ds_y", "three_ds_a", "three_ds_u", "three_ds_n", "three_ds_r", "three_ds_not_attempted", "gdpr_art22_explanation_required", "pci_token_only", "pci_last4_only", "facta_red_flag_match", "fincen_8300_threshold_met", "eu_ai_act_high_risk_processing", "ccpa_admt_notice_required", "none" ], "type": "string" }, "title": "Compliance flags observed during scoring", "type": "array" }, "prior_triage_ref": { "format": "uuid", "title": "Optional cross-surface link to a prior message_triage (e.g. injection.suspected)", "type": "string", "x-aerandil-references": "hospitality.message_triage" }, "rationale_text": { "title": "Human-readable explanation", "type": "string" }, "reason_codes": { "title": "Explanation array (JSON array of {code, severity, contribution})" }, "recommended_action": { "enum": [ "approve", "review", "step_up_3ds", "step_up_kyc", "decline", "escalate" ], "title": "Recommended action class", "type": "string" }, "reservation_ref": { "format": "uuid", "title": "Optional denormalised reservation anchor", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "risk_context_snapshot": { "additionalProperties": true, "title": "Frozen context snapshot at issue time (JSON; host populates per recommended shape)", "type": "object" }, "score": { "format": "decimal", "title": "Raw numeric score on the [0, 100] scale", "type": "string" }, "score_calibrated": { "format": "decimal", "title": "Optional calibrated probability [0, 1]", "type": "string" }, "subject_id": { "title": "Id of the typed object the assessment scored", "type": "string" }, "subject_kind": { "enum": [ "reservation", "payment", "charge", "person", "loyalty_redemption", "folio" ], "title": "What kind of object the assessment scored", "type": "string" }, "triggered_rules": { "title": "Custom-rule provenance (JSON array of {rule_id, rule_version, action})" }, "vendor_id": { "title": "Vendor identity (denormalised from Principal::Agent.vendor)", "type": "string" }, "vendor_model_version": { "title": "Vendor model version when exposed", "type": "string" } }, "required": [ "subject_kind", "subject_id", "fire_point", "vendor_id", "score", "band", "recommended_action", "confidence", "factors_considered", "reason_codes", "rationale_text", "risk_context_snapshot", "policy_outcomes" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.fraud_assessment_for_reservation", "hospitality.link.fraud_assessment_for_person", "hospitality.link.fraud_assessment_for_charge", "hospitality.link.fraud_assessment_at_property", "hospitality.link.fraud_assessment_references_external_record", "hospitality.link.fraud_assessment_superseded_by", "hospitality.link.fraud_assessment_for_prior_triage", "hospitality.link.fraud_assessment_consulted_network" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.fraud_risk_assessment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Detect fraud risk (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.detect_fraud_risk/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_detect_fraud_risk`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_detect_fraud_risk", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "band": { "enum": [ "low", "medium", "high", "block", "not_assessed" ], "title": "Risk band ordinal", "type": "string" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Operator-facing confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Calibrated probability [0, 1] (optional)", "type": "string" }, "coverage_guaranteed": { "title": "True when the vendor's chargeback-guarantee covers this decision", "type": "boolean" }, "coverage_terms_uri": { "title": "Pointer to the vendor's coverage terms", "type": "string" }, "expires_at": { "format": "date-time", "title": "Assessment expiry (default per fire-point — see proposal §3.1)", "type": "string" }, "external_record_ref": { "format": "uuid", "title": "Optional pointer to vendor raw payload (external_record_reference)", "type": "string", "x-aerandil-references": "hospitality.external_record_reference" }, "factors_considered": { "items": { "enum": [ "payment_signal", "identity_signal", "behavioural_signal", "device_signal", "velocity_signal", "geo_signal", "lead_time", "loyalty_account_age", "prior_chargeback_history", "prior_recovery_history", "third_party_payer_flag", "vcn_detected", "injection_history", "network_outcome", "kyc_outcome", "three_ds_outcome", "watchlist_match", "graph_signal", "fraud_network_signal", "other" ], "type": "string" }, "title": "Signals the assessment conditioned on", "type": "array" }, "feature_payload_hash": { "title": "SHA-256 of canonical input-feature JSON (chargeback-defence tamper-evidence)", "type": "string" }, "fire_point": { "enum": [ "at_booking", "at_payment", "at_check_in", "at_folio_close", "on_chargeback_attempt" ], "title": "Lifecycle moment the assessment fired at", "type": "string" }, "folio_charge_ref": { "format": "uuid", "title": "Optional charge anchor", "type": "string", "x-aerandil-references": "hospitality.charge" }, "fraud_network_signal_ref": { "format": "uuid", "title": "The Watchtower answer this assessment was scored with; its band floor binds the band", "type": "string", "x-aerandil-references": "hospitality.fraud_network_signal" }, "person_ref": { "format": "uuid", "title": "Optional denormalised person anchor", "type": "string", "x-aerandil-references": "hospitality.person" }, "policy_outcomes": { "items": { "enum": [ "psd2_sca_required", "psd2_sca_out_of_scope_moto", "psd2_sca_exempted_low_value", "psd2_sca_exempted_trusted_beneficiaries", "psd2_sca_exempted_tra", "psd2_sca_exempted_recurring", "psd2_sca_exempted_corporate_payment", "three_ds_y", "three_ds_a", "three_ds_u", "three_ds_n", "three_ds_r", "three_ds_not_attempted", "gdpr_art22_explanation_required", "pci_token_only", "pci_last4_only", "facta_red_flag_match", "fincen_8300_threshold_met", "eu_ai_act_high_risk_processing", "ccpa_admt_notice_required", "none" ], "type": "string" }, "title": "Compliance flags observed during scoring", "type": "array" }, "prior_triage_ref": { "format": "uuid", "title": "Optional cross-surface link to a prior message_triage (e.g. injection.suspected)", "type": "string", "x-aerandil-references": "hospitality.message_triage" }, "rationale_text": { "title": "Human-readable explanation", "type": "string" }, "reason_codes": { "title": "Explanation array (JSON array of {code, severity, contribution})" }, "recommended_action": { "enum": [ "approve", "review", "step_up_3ds", "step_up_kyc", "decline", "escalate" ], "title": "Recommended action class", "type": "string" }, "reservation_ref": { "format": "uuid", "title": "Optional denormalised reservation anchor", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "risk_context_snapshot": { "additionalProperties": true, "title": "Frozen context snapshot at issue time (JSON; host populates per recommended shape)", "type": "object" }, "score": { "format": "decimal", "title": "Raw numeric score on the [0, 100] scale", "type": "string" }, "score_calibrated": { "format": "decimal", "title": "Optional calibrated probability [0, 1]", "type": "string" }, "subject_id": { "title": "Id of the typed object the assessment scored", "type": "string" }, "subject_kind": { "enum": [ "reservation", "payment", "charge", "person", "loyalty_redemption", "folio" ], "title": "What kind of object the assessment scored", "type": "string" }, "triggered_rules": { "title": "Custom-rule provenance (JSON array of {rule_id, rule_version, action})" }, "vendor_id": { "title": "Vendor identity (denormalised from Principal::Agent.vendor)", "type": "string" }, "vendor_model_version": { "title": "Vendor model version when exposed", "type": "string" } }, "required": [ "subject_kind", "subject_id", "fire_point", "vendor_id", "score", "band", "recommended_action", "confidence", "factors_considered", "reason_codes", "rationale_text", "risk_context_snapshot", "policy_outcomes" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Detect fraud risk (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.detect_fraud_risk/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_detect_fraud_risk` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.detect_fraud_risk:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_detect_fraud_risk", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "band": { "enum": [ "low", "medium", "high", "block", "not_assessed" ], "title": "Risk band ordinal", "type": "string" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Operator-facing confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Calibrated probability [0, 1] (optional)", "type": "string" }, "coverage_guaranteed": { "title": "True when the vendor's chargeback-guarantee covers this decision", "type": "boolean" }, "coverage_terms_uri": { "title": "Pointer to the vendor's coverage terms", "type": "string" }, "expires_at": { "format": "date-time", "title": "Assessment expiry (default per fire-point — see proposal §3.1)", "type": "string" }, "external_record_ref": { "format": "uuid", "title": "Optional pointer to vendor raw payload (external_record_reference)", "type": "string", "x-aerandil-references": "hospitality.external_record_reference" }, "factors_considered": { "items": { "enum": [ "payment_signal", "identity_signal", "behavioural_signal", "device_signal", "velocity_signal", "geo_signal", "lead_time", "loyalty_account_age", "prior_chargeback_history", "prior_recovery_history", "third_party_payer_flag", "vcn_detected", "injection_history", "network_outcome", "kyc_outcome", "three_ds_outcome", "watchlist_match", "graph_signal", "fraud_network_signal", "other" ], "type": "string" }, "title": "Signals the assessment conditioned on", "type": "array" }, "feature_payload_hash": { "title": "SHA-256 of canonical input-feature JSON (chargeback-defence tamper-evidence)", "type": "string" }, "fire_point": { "enum": [ "at_booking", "at_payment", "at_check_in", "at_folio_close", "on_chargeback_attempt" ], "title": "Lifecycle moment the assessment fired at", "type": "string" }, "folio_charge_ref": { "format": "uuid", "title": "Optional charge anchor", "type": "string", "x-aerandil-references": "hospitality.charge" }, "fraud_network_signal_ref": { "format": "uuid", "title": "The Watchtower answer this assessment was scored with; its band floor binds the band", "type": "string", "x-aerandil-references": "hospitality.fraud_network_signal" }, "person_ref": { "format": "uuid", "title": "Optional denormalised person anchor", "type": "string", "x-aerandil-references": "hospitality.person" }, "policy_outcomes": { "items": { "enum": [ "psd2_sca_required", "psd2_sca_out_of_scope_moto", "psd2_sca_exempted_low_value", "psd2_sca_exempted_trusted_beneficiaries", "psd2_sca_exempted_tra", "psd2_sca_exempted_recurring", "psd2_sca_exempted_corporate_payment", "three_ds_y", "three_ds_a", "three_ds_u", "three_ds_n", "three_ds_r", "three_ds_not_attempted", "gdpr_art22_explanation_required", "pci_token_only", "pci_last4_only", "facta_red_flag_match", "fincen_8300_threshold_met", "eu_ai_act_high_risk_processing", "ccpa_admt_notice_required", "none" ], "type": "string" }, "title": "Compliance flags observed during scoring", "type": "array" }, "prior_triage_ref": { "format": "uuid", "title": "Optional cross-surface link to a prior message_triage (e.g. injection.suspected)", "type": "string", "x-aerandil-references": "hospitality.message_triage" }, "rationale_text": { "title": "Human-readable explanation", "type": "string" }, "reason_codes": { "title": "Explanation array (JSON array of {code, severity, contribution})" }, "recommended_action": { "enum": [ "approve", "review", "step_up_3ds", "step_up_kyc", "decline", "escalate" ], "title": "Recommended action class", "type": "string" }, "reservation_ref": { "format": "uuid", "title": "Optional denormalised reservation anchor", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "risk_context_snapshot": { "additionalProperties": true, "title": "Frozen context snapshot at issue time (JSON; host populates per recommended shape)", "type": "object" }, "score": { "format": "decimal", "title": "Raw numeric score on the [0, 100] scale", "type": "string" }, "score_calibrated": { "format": "decimal", "title": "Optional calibrated probability [0, 1]", "type": "string" }, "subject_id": { "title": "Id of the typed object the assessment scored", "type": "string" }, "subject_kind": { "enum": [ "reservation", "payment", "charge", "person", "loyalty_redemption", "folio" ], "title": "What kind of object the assessment scored", "type": "string" }, "triggered_rules": { "title": "Custom-rule provenance (JSON array of {rule_id, rule_version, action})" }, "vendor_id": { "title": "Vendor identity (denormalised from Principal::Agent.vendor)", "type": "string" }, "vendor_model_version": { "title": "Vendor model version when exposed", "type": "string" } }, "required": [ "subject_kind", "subject_id", "fire_point", "vendor_id", "score", "band", "recommended_action", "confidence", "factors_considered", "reason_codes", "rationale_text", "risk_context_snapshot", "policy_outcomes" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Detect fraud risk (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.detect_recurring_failure_pattern/apply": { "post": { "description": "Emit a typed service_recovery_pattern in suggested state. The action targets the property container; subject_kind and subject_id identify the clustered operational subject. A run_id may be supplied or the handler can open a manual run.\n\nEffects: create hospitality.service_recovery_pattern; modify hospitality.recovery_pattern_detection_run; link hospitality.link.pattern_part_of_run; link hospitality.link.pattern_at_property; link hospitality.link.pattern_at_venue; link hospitality.link.pattern_at_room; link hospitality.link.pattern_superseded_by; link hospitality.link.pattern_references_external_record; link hospitality.link.pattern_references_service_philosophy; link hospitality.link.pattern_clusters_recovery_event; link hospitality.link.pattern_clusters_message_triage; link hospitality.link.pattern_clusters_work_order; link hospitality.link.pattern_clusters_housekeeping_task; link hospitality.link.pattern_clusters_pre_shift_lineup_event; create hospitality.recovery_pattern_detection_run; link hospitality.link.recovery_pattern_run_for_property.", "operationId": "apply_hospitality_action_detect_recurring_failure_pattern", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "confidence": { "enum": [ "low", "medium", "high" ], "title": "Confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Optional calibrated confidence score [0, 1]", "type": "string" }, "detection_window_end": { "format": "date-time", "title": "Detection window end", "type": "string" }, "detection_window_start": { "format": "date-time", "title": "Detection window start", "type": "string" }, "event_count": { "title": "Clustered event count", "type": "integer" }, "expires_at": { "format": "date-time", "title": "Expiry", "type": "string" }, "external_record_ref": { "format": "uuid", "title": "Optional vendor raw-payload reference", "type": "string", "x-aerandil-references": "hospitality.external_record_reference" }, "factors_considered": { "items": { "enum": [ "recovery_event_density", "recovery_event_severity_distribution", "recovery_event_temporal_clustering", "recovery_event_venue_clustering", "recovery_event_room_clustering", "comp_amount_distribution", "recovery_process_stages_completion_rate", "interactional_quality_distribution", "time_to_resolution_distribution", "pre_shift_lineup_cadence", "message_triage_complaint_density", "work_order_recurrence", "housekeeping_task_defect_rate", "review_sentiment_trend", "philosophy_axis_contradiction", "recovery_paradox_signal", "staff_member_turnover", "other" ], "type": "string" }, "title": "Signals considered", "type": "array" }, "failure_categories_observed": { "items": { "enum": [ "staff_interaction", "room_condition", "fnb_quality", "fnb_service_pace", "billing", "allergy_dietary", "security_safety", "check_in_out", "maintenance", "recognition_failure", "anticipation_miss", "noise", "temperature", "other" ], "type": "string" }, "title": "Observed failure categories", "type": "array" }, "failure_subject_themes": { "items": { "type": "string" }, "title": "Subject theme labels", "type": "array" }, "housekeeping_task_refs": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.housekeeping_task" }, "title": "Optional clustered housekeeping tasks", "type": "array" }, "message_triage_refs": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.message_triage" }, "title": "Optional clustered message triages", "type": "array" }, "pattern_context_snapshot": { "additionalProperties": true, "title": "Frozen context snapshot", "type": "object" }, "pattern_kind": { "enum": [ "recurring_failure_category", "venue_hotspot", "room_or_floor_hotspot", "time_window_hotspot", "staff_role_hotspot", "cross_signal_correlation", "comp_authority_breach_spike", "lineup_cadence_drift", "recognition_failure_against_philosophy", "recovery_paradox_breach", "follow_up_completion_drop", "other" ], "title": "Detected pattern class", "type": "string" }, "policy_outcomes": { "items": { "enum": [ "gdpr_art22_explanation_required", "eu_ai_act_high_risk_processing", "ccpa_admt_notice_required", "health_safety_referral", "gdpr_art9_special_category_present", "privacy_redaction_applied", "ccpa_admt_significant_decision", "capex_threshold_breached", "none" ], "type": "string" }, "title": "Policy flags", "type": "array" }, "pre_shift_lineup_event_refs": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.pre_shift_lineup_event" }, "title": "Optional clustered pre-shift lineup events", "type": "array" }, "rationale_text": { "title": "Explanation", "type": "string" }, "recommended_remediation_action_ref": { "title": "API name of the host-orchestrated chained action", "type": "string" }, "recommended_remediation_kind": { "enum": [ "chain_typed_action", "schedule_capital_expenditure_review", "escalate_to_staff", "philosophy_revisit", "continue_monitoring", "cross_property_review", "update_service_register", "no_action_recommended", "update_recovery_toolkit", "data_quality_followup", "schedule_staff_training", "other" ], "title": "Recommended remediation class", "type": "string" }, "recommended_remediation_params": { "additionalProperties": true, "title": "Proposed remediation params", "type": "object" }, "recovery_event_refs": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.service_recovery_event" }, "title": "Optional clustered service recovery events", "type": "array" }, "room_ref": { "format": "uuid", "title": "Optional room anchor for room/floor patterns", "type": "string", "x-aerandil-references": "hospitality.room" }, "root_cause_hypotheses": { "items": { "properties": { "contribution": { "format": "decimal", "type": "string" }, "kind": { "enum": [ "equipment_malfunction", "maintenance_overdue", "supply_shortage", "staffing_shortage", "training_gap", "process_gap", "scheduling_conflict", "supplier_quality_issue", "seasonal_event", "external_event", "data_quality_issue", "unknown" ], "type": "string" }, "narrative_text": { "type": "string" } }, "required": [ "kind", "narrative_text", "contribution" ], "type": "object" }, "title": "Structured root-cause hypotheses", "type": "array" }, "run_id": { "title": "Optional run UUID", "type": "string" }, "service_philosophy_ref": { "format": "uuid", "title": "Optional referenced service philosophy", "type": "string", "x-aerandil-references": "hospitality.service_philosophy" }, "severity_band": { "enum": [ "low", "medium", "high", "critical" ], "title": "Severity band", "type": "string" }, "severity_score": { "format": "decimal", "title": "Optional calibrated severity score [0, 1]", "type": "string" }, "subject_id": { "title": "Clustered subject id", "type": "string" }, "subject_kind": { "enum": [ "failure_category_hotspot", "venue_hotspot", "room_or_floor_hotspot", "time_window_hotspot", "staff_role_hotspot", "cross_signal_correlation", "comp_authority_breach_spike", "lineup_cadence_drift", "recognition_failure_against_philosophy", "recovery_paradox_breach" ], "title": "Clustered subject kind", "type": "string" }, "vendor_id": { "title": "Detector vendor identity", "type": "string" }, "vendor_model_version": { "title": "Detector model version", "type": "string" }, "venue_ref": { "format": "uuid", "title": "Optional venue anchor", "type": "string", "x-aerandil-references": "hospitality.venue" }, "work_order_refs": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.work_order" }, "title": "Optional clustered work orders", "type": "array" } }, "required": [ "subject_kind", "subject_id", "detection_window_start", "detection_window_end", "pattern_kind", "event_count", "severity_band", "failure_categories_observed", "failure_subject_themes", "vendor_id", "confidence", "factors_considered", "root_cause_hypotheses", "recommended_remediation_kind", "rationale_text", "pattern_context_snapshot", "policy_outcomes" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.pattern_part_of_run", "hospitality.link.pattern_at_property", "hospitality.link.pattern_at_venue", "hospitality.link.pattern_at_room", "hospitality.link.pattern_superseded_by", "hospitality.link.pattern_references_external_record", "hospitality.link.pattern_references_service_philosophy", "hospitality.link.pattern_clusters_recovery_event", "hospitality.link.pattern_clusters_message_triage", "hospitality.link.pattern_clusters_work_order", "hospitality.link.pattern_clusters_housekeeping_task", "hospitality.link.pattern_clusters_pre_shift_lineup_event", "hospitality.link.recovery_pattern_run_for_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.service_recovery_pattern", "hospitality.recovery_pattern_detection_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.detect_recurring_failure_pattern:apply" ] } ], "summary": "Detect recurring failure pattern", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.detect_recurring_failure_pattern/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_detect_recurring_failure_pattern` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.detect_recurring_failure_pattern:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_detect_recurring_failure_pattern", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "confidence": { "enum": [ "low", "medium", "high" ], "title": "Confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Optional calibrated confidence score [0, 1]", "type": "string" }, "detection_window_end": { "format": "date-time", "title": "Detection window end", "type": "string" }, "detection_window_start": { "format": "date-time", "title": "Detection window start", "type": "string" }, "event_count": { "title": "Clustered event count", "type": "integer" }, "expires_at": { "format": "date-time", "title": "Expiry", "type": "string" }, "external_record_ref": { "format": "uuid", "title": "Optional vendor raw-payload reference", "type": "string", "x-aerandil-references": "hospitality.external_record_reference" }, "factors_considered": { "items": { "enum": [ "recovery_event_density", "recovery_event_severity_distribution", "recovery_event_temporal_clustering", "recovery_event_venue_clustering", "recovery_event_room_clustering", "comp_amount_distribution", "recovery_process_stages_completion_rate", "interactional_quality_distribution", "time_to_resolution_distribution", "pre_shift_lineup_cadence", "message_triage_complaint_density", "work_order_recurrence", "housekeeping_task_defect_rate", "review_sentiment_trend", "philosophy_axis_contradiction", "recovery_paradox_signal", "staff_member_turnover", "other" ], "type": "string" }, "title": "Signals considered", "type": "array" }, "failure_categories_observed": { "items": { "enum": [ "staff_interaction", "room_condition", "fnb_quality", "fnb_service_pace", "billing", "allergy_dietary", "security_safety", "check_in_out", "maintenance", "recognition_failure", "anticipation_miss", "noise", "temperature", "other" ], "type": "string" }, "title": "Observed failure categories", "type": "array" }, "failure_subject_themes": { "items": { "type": "string" }, "title": "Subject theme labels", "type": "array" }, "housekeeping_task_refs": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.housekeeping_task" }, "title": "Optional clustered housekeeping tasks", "type": "array" }, "message_triage_refs": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.message_triage" }, "title": "Optional clustered message triages", "type": "array" }, "pattern_context_snapshot": { "additionalProperties": true, "title": "Frozen context snapshot", "type": "object" }, "pattern_kind": { "enum": [ "recurring_failure_category", "venue_hotspot", "room_or_floor_hotspot", "time_window_hotspot", "staff_role_hotspot", "cross_signal_correlation", "comp_authority_breach_spike", "lineup_cadence_drift", "recognition_failure_against_philosophy", "recovery_paradox_breach", "follow_up_completion_drop", "other" ], "title": "Detected pattern class", "type": "string" }, "policy_outcomes": { "items": { "enum": [ "gdpr_art22_explanation_required", "eu_ai_act_high_risk_processing", "ccpa_admt_notice_required", "health_safety_referral", "gdpr_art9_special_category_present", "privacy_redaction_applied", "ccpa_admt_significant_decision", "capex_threshold_breached", "none" ], "type": "string" }, "title": "Policy flags", "type": "array" }, "pre_shift_lineup_event_refs": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.pre_shift_lineup_event" }, "title": "Optional clustered pre-shift lineup events", "type": "array" }, "rationale_text": { "title": "Explanation", "type": "string" }, "recommended_remediation_action_ref": { "title": "API name of the host-orchestrated chained action", "type": "string" }, "recommended_remediation_kind": { "enum": [ "chain_typed_action", "schedule_capital_expenditure_review", "escalate_to_staff", "philosophy_revisit", "continue_monitoring", "cross_property_review", "update_service_register", "no_action_recommended", "update_recovery_toolkit", "data_quality_followup", "schedule_staff_training", "other" ], "title": "Recommended remediation class", "type": "string" }, "recommended_remediation_params": { "additionalProperties": true, "title": "Proposed remediation params", "type": "object" }, "recovery_event_refs": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.service_recovery_event" }, "title": "Optional clustered service recovery events", "type": "array" }, "room_ref": { "format": "uuid", "title": "Optional room anchor for room/floor patterns", "type": "string", "x-aerandil-references": "hospitality.room" }, "root_cause_hypotheses": { "items": { "properties": { "contribution": { "format": "decimal", "type": "string" }, "kind": { "enum": [ "equipment_malfunction", "maintenance_overdue", "supply_shortage", "staffing_shortage", "training_gap", "process_gap", "scheduling_conflict", "supplier_quality_issue", "seasonal_event", "external_event", "data_quality_issue", "unknown" ], "type": "string" }, "narrative_text": { "type": "string" } }, "required": [ "kind", "narrative_text", "contribution" ], "type": "object" }, "title": "Structured root-cause hypotheses", "type": "array" }, "run_id": { "title": "Optional run UUID", "type": "string" }, "service_philosophy_ref": { "format": "uuid", "title": "Optional referenced service philosophy", "type": "string", "x-aerandil-references": "hospitality.service_philosophy" }, "severity_band": { "enum": [ "low", "medium", "high", "critical" ], "title": "Severity band", "type": "string" }, "severity_score": { "format": "decimal", "title": "Optional calibrated severity score [0, 1]", "type": "string" }, "subject_id": { "title": "Clustered subject id", "type": "string" }, "subject_kind": { "enum": [ "failure_category_hotspot", "venue_hotspot", "room_or_floor_hotspot", "time_window_hotspot", "staff_role_hotspot", "cross_signal_correlation", "comp_authority_breach_spike", "lineup_cadence_drift", "recognition_failure_against_philosophy", "recovery_paradox_breach" ], "title": "Clustered subject kind", "type": "string" }, "vendor_id": { "title": "Detector vendor identity", "type": "string" }, "vendor_model_version": { "title": "Detector model version", "type": "string" }, "venue_ref": { "format": "uuid", "title": "Optional venue anchor", "type": "string", "x-aerandil-references": "hospitality.venue" }, "work_order_refs": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.work_order" }, "title": "Optional clustered work orders", "type": "array" } }, "required": [ "subject_kind", "subject_id", "detection_window_start", "detection_window_end", "pattern_kind", "event_count", "severity_band", "failure_categories_observed", "failure_subject_themes", "vendor_id", "confidence", "factors_considered", "root_cause_hypotheses", "recommended_remediation_kind", "rationale_text", "pattern_context_snapshot", "policy_outcomes" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.pattern_part_of_run", "hospitality.link.pattern_at_property", "hospitality.link.pattern_at_venue", "hospitality.link.pattern_at_room", "hospitality.link.pattern_superseded_by", "hospitality.link.pattern_references_external_record", "hospitality.link.pattern_references_service_philosophy", "hospitality.link.pattern_clusters_recovery_event", "hospitality.link.pattern_clusters_message_triage", "hospitality.link.pattern_clusters_work_order", "hospitality.link.pattern_clusters_housekeeping_task", "hospitality.link.pattern_clusters_pre_shift_lineup_event", "hospitality.link.recovery_pattern_run_for_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.service_recovery_pattern", "hospitality.recovery_pattern_detection_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Detect recurring failure pattern (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.detect_recurring_failure_pattern/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_detect_recurring_failure_pattern`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_detect_recurring_failure_pattern", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "confidence": { "enum": [ "low", "medium", "high" ], "title": "Confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Optional calibrated confidence score [0, 1]", "type": "string" }, "detection_window_end": { "format": "date-time", "title": "Detection window end", "type": "string" }, "detection_window_start": { "format": "date-time", "title": "Detection window start", "type": "string" }, "event_count": { "title": "Clustered event count", "type": "integer" }, "expires_at": { "format": "date-time", "title": "Expiry", "type": "string" }, "external_record_ref": { "format": "uuid", "title": "Optional vendor raw-payload reference", "type": "string", "x-aerandil-references": "hospitality.external_record_reference" }, "factors_considered": { "items": { "enum": [ "recovery_event_density", "recovery_event_severity_distribution", "recovery_event_temporal_clustering", "recovery_event_venue_clustering", "recovery_event_room_clustering", "comp_amount_distribution", "recovery_process_stages_completion_rate", "interactional_quality_distribution", "time_to_resolution_distribution", "pre_shift_lineup_cadence", "message_triage_complaint_density", "work_order_recurrence", "housekeeping_task_defect_rate", "review_sentiment_trend", "philosophy_axis_contradiction", "recovery_paradox_signal", "staff_member_turnover", "other" ], "type": "string" }, "title": "Signals considered", "type": "array" }, "failure_categories_observed": { "items": { "enum": [ "staff_interaction", "room_condition", "fnb_quality", "fnb_service_pace", "billing", "allergy_dietary", "security_safety", "check_in_out", "maintenance", "recognition_failure", "anticipation_miss", "noise", "temperature", "other" ], "type": "string" }, "title": "Observed failure categories", "type": "array" }, "failure_subject_themes": { "items": { "type": "string" }, "title": "Subject theme labels", "type": "array" }, "housekeeping_task_refs": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.housekeeping_task" }, "title": "Optional clustered housekeeping tasks", "type": "array" }, "message_triage_refs": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.message_triage" }, "title": "Optional clustered message triages", "type": "array" }, "pattern_context_snapshot": { "additionalProperties": true, "title": "Frozen context snapshot", "type": "object" }, "pattern_kind": { "enum": [ "recurring_failure_category", "venue_hotspot", "room_or_floor_hotspot", "time_window_hotspot", "staff_role_hotspot", "cross_signal_correlation", "comp_authority_breach_spike", "lineup_cadence_drift", "recognition_failure_against_philosophy", "recovery_paradox_breach", "follow_up_completion_drop", "other" ], "title": "Detected pattern class", "type": "string" }, "policy_outcomes": { "items": { "enum": [ "gdpr_art22_explanation_required", "eu_ai_act_high_risk_processing", "ccpa_admt_notice_required", "health_safety_referral", "gdpr_art9_special_category_present", "privacy_redaction_applied", "ccpa_admt_significant_decision", "capex_threshold_breached", "none" ], "type": "string" }, "title": "Policy flags", "type": "array" }, "pre_shift_lineup_event_refs": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.pre_shift_lineup_event" }, "title": "Optional clustered pre-shift lineup events", "type": "array" }, "rationale_text": { "title": "Explanation", "type": "string" }, "recommended_remediation_action_ref": { "title": "API name of the host-orchestrated chained action", "type": "string" }, "recommended_remediation_kind": { "enum": [ "chain_typed_action", "schedule_capital_expenditure_review", "escalate_to_staff", "philosophy_revisit", "continue_monitoring", "cross_property_review", "update_service_register", "no_action_recommended", "update_recovery_toolkit", "data_quality_followup", "schedule_staff_training", "other" ], "title": "Recommended remediation class", "type": "string" }, "recommended_remediation_params": { "additionalProperties": true, "title": "Proposed remediation params", "type": "object" }, "recovery_event_refs": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.service_recovery_event" }, "title": "Optional clustered service recovery events", "type": "array" }, "room_ref": { "format": "uuid", "title": "Optional room anchor for room/floor patterns", "type": "string", "x-aerandil-references": "hospitality.room" }, "root_cause_hypotheses": { "items": { "properties": { "contribution": { "format": "decimal", "type": "string" }, "kind": { "enum": [ "equipment_malfunction", "maintenance_overdue", "supply_shortage", "staffing_shortage", "training_gap", "process_gap", "scheduling_conflict", "supplier_quality_issue", "seasonal_event", "external_event", "data_quality_issue", "unknown" ], "type": "string" }, "narrative_text": { "type": "string" } }, "required": [ "kind", "narrative_text", "contribution" ], "type": "object" }, "title": "Structured root-cause hypotheses", "type": "array" }, "run_id": { "title": "Optional run UUID", "type": "string" }, "service_philosophy_ref": { "format": "uuid", "title": "Optional referenced service philosophy", "type": "string", "x-aerandil-references": "hospitality.service_philosophy" }, "severity_band": { "enum": [ "low", "medium", "high", "critical" ], "title": "Severity band", "type": "string" }, "severity_score": { "format": "decimal", "title": "Optional calibrated severity score [0, 1]", "type": "string" }, "subject_id": { "title": "Clustered subject id", "type": "string" }, "subject_kind": { "enum": [ "failure_category_hotspot", "venue_hotspot", "room_or_floor_hotspot", "time_window_hotspot", "staff_role_hotspot", "cross_signal_correlation", "comp_authority_breach_spike", "lineup_cadence_drift", "recognition_failure_against_philosophy", "recovery_paradox_breach" ], "title": "Clustered subject kind", "type": "string" }, "vendor_id": { "title": "Detector vendor identity", "type": "string" }, "vendor_model_version": { "title": "Detector model version", "type": "string" }, "venue_ref": { "format": "uuid", "title": "Optional venue anchor", "type": "string", "x-aerandil-references": "hospitality.venue" }, "work_order_refs": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.work_order" }, "title": "Optional clustered work orders", "type": "array" } }, "required": [ "subject_kind", "subject_id", "detection_window_start", "detection_window_end", "pattern_kind", "event_count", "severity_band", "failure_categories_observed", "failure_subject_themes", "vendor_id", "confidence", "factors_considered", "root_cause_hypotheses", "recommended_remediation_kind", "rationale_text", "pattern_context_snapshot", "policy_outcomes" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Detect recurring failure pattern (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.detect_recurring_failure_pattern/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_detect_recurring_failure_pattern` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.detect_recurring_failure_pattern:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_detect_recurring_failure_pattern", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "confidence": { "enum": [ "low", "medium", "high" ], "title": "Confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Optional calibrated confidence score [0, 1]", "type": "string" }, "detection_window_end": { "format": "date-time", "title": "Detection window end", "type": "string" }, "detection_window_start": { "format": "date-time", "title": "Detection window start", "type": "string" }, "event_count": { "title": "Clustered event count", "type": "integer" }, "expires_at": { "format": "date-time", "title": "Expiry", "type": "string" }, "external_record_ref": { "format": "uuid", "title": "Optional vendor raw-payload reference", "type": "string", "x-aerandil-references": "hospitality.external_record_reference" }, "factors_considered": { "items": { "enum": [ "recovery_event_density", "recovery_event_severity_distribution", "recovery_event_temporal_clustering", "recovery_event_venue_clustering", "recovery_event_room_clustering", "comp_amount_distribution", "recovery_process_stages_completion_rate", "interactional_quality_distribution", "time_to_resolution_distribution", "pre_shift_lineup_cadence", "message_triage_complaint_density", "work_order_recurrence", "housekeeping_task_defect_rate", "review_sentiment_trend", "philosophy_axis_contradiction", "recovery_paradox_signal", "staff_member_turnover", "other" ], "type": "string" }, "title": "Signals considered", "type": "array" }, "failure_categories_observed": { "items": { "enum": [ "staff_interaction", "room_condition", "fnb_quality", "fnb_service_pace", "billing", "allergy_dietary", "security_safety", "check_in_out", "maintenance", "recognition_failure", "anticipation_miss", "noise", "temperature", "other" ], "type": "string" }, "title": "Observed failure categories", "type": "array" }, "failure_subject_themes": { "items": { "type": "string" }, "title": "Subject theme labels", "type": "array" }, "housekeeping_task_refs": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.housekeeping_task" }, "title": "Optional clustered housekeeping tasks", "type": "array" }, "message_triage_refs": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.message_triage" }, "title": "Optional clustered message triages", "type": "array" }, "pattern_context_snapshot": { "additionalProperties": true, "title": "Frozen context snapshot", "type": "object" }, "pattern_kind": { "enum": [ "recurring_failure_category", "venue_hotspot", "room_or_floor_hotspot", "time_window_hotspot", "staff_role_hotspot", "cross_signal_correlation", "comp_authority_breach_spike", "lineup_cadence_drift", "recognition_failure_against_philosophy", "recovery_paradox_breach", "follow_up_completion_drop", "other" ], "title": "Detected pattern class", "type": "string" }, "policy_outcomes": { "items": { "enum": [ "gdpr_art22_explanation_required", "eu_ai_act_high_risk_processing", "ccpa_admt_notice_required", "health_safety_referral", "gdpr_art9_special_category_present", "privacy_redaction_applied", "ccpa_admt_significant_decision", "capex_threshold_breached", "none" ], "type": "string" }, "title": "Policy flags", "type": "array" }, "pre_shift_lineup_event_refs": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.pre_shift_lineup_event" }, "title": "Optional clustered pre-shift lineup events", "type": "array" }, "rationale_text": { "title": "Explanation", "type": "string" }, "recommended_remediation_action_ref": { "title": "API name of the host-orchestrated chained action", "type": "string" }, "recommended_remediation_kind": { "enum": [ "chain_typed_action", "schedule_capital_expenditure_review", "escalate_to_staff", "philosophy_revisit", "continue_monitoring", "cross_property_review", "update_service_register", "no_action_recommended", "update_recovery_toolkit", "data_quality_followup", "schedule_staff_training", "other" ], "title": "Recommended remediation class", "type": "string" }, "recommended_remediation_params": { "additionalProperties": true, "title": "Proposed remediation params", "type": "object" }, "recovery_event_refs": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.service_recovery_event" }, "title": "Optional clustered service recovery events", "type": "array" }, "room_ref": { "format": "uuid", "title": "Optional room anchor for room/floor patterns", "type": "string", "x-aerandil-references": "hospitality.room" }, "root_cause_hypotheses": { "items": { "properties": { "contribution": { "format": "decimal", "type": "string" }, "kind": { "enum": [ "equipment_malfunction", "maintenance_overdue", "supply_shortage", "staffing_shortage", "training_gap", "process_gap", "scheduling_conflict", "supplier_quality_issue", "seasonal_event", "external_event", "data_quality_issue", "unknown" ], "type": "string" }, "narrative_text": { "type": "string" } }, "required": [ "kind", "narrative_text", "contribution" ], "type": "object" }, "title": "Structured root-cause hypotheses", "type": "array" }, "run_id": { "title": "Optional run UUID", "type": "string" }, "service_philosophy_ref": { "format": "uuid", "title": "Optional referenced service philosophy", "type": "string", "x-aerandil-references": "hospitality.service_philosophy" }, "severity_band": { "enum": [ "low", "medium", "high", "critical" ], "title": "Severity band", "type": "string" }, "severity_score": { "format": "decimal", "title": "Optional calibrated severity score [0, 1]", "type": "string" }, "subject_id": { "title": "Clustered subject id", "type": "string" }, "subject_kind": { "enum": [ "failure_category_hotspot", "venue_hotspot", "room_or_floor_hotspot", "time_window_hotspot", "staff_role_hotspot", "cross_signal_correlation", "comp_authority_breach_spike", "lineup_cadence_drift", "recognition_failure_against_philosophy", "recovery_paradox_breach" ], "title": "Clustered subject kind", "type": "string" }, "vendor_id": { "title": "Detector vendor identity", "type": "string" }, "vendor_model_version": { "title": "Detector model version", "type": "string" }, "venue_ref": { "format": "uuid", "title": "Optional venue anchor", "type": "string", "x-aerandil-references": "hospitality.venue" }, "work_order_refs": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.work_order" }, "title": "Optional clustered work orders", "type": "array" } }, "required": [ "subject_kind", "subject_id", "detection_window_start", "detection_window_end", "pattern_kind", "event_count", "severity_band", "failure_categories_observed", "failure_subject_themes", "vendor_id", "confidence", "factors_considered", "root_cause_hypotheses", "recommended_remediation_kind", "rationale_text", "pattern_context_snapshot", "policy_outcomes" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Detect recurring failure pattern (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.dispatch_room_service/apply": { "post": { "description": "An in-room dining order leaves the kitchen: the target room-service check's `delivery_status` goes `taken` → `dispatched`, stamping `dispatched_at`, the `runner_id` who takes it up and its `conveyance` (`tray` or `trolley` — what has to come back down). Only a room_service check, and only from `taken`; the check may be open or already settled. Emits `fnb.room_service_dispatched`.\n\nEffects: modify hospitality.guest_check.", "operationId": "apply_hospitality_action_dispatch_room_service", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "conveyance": { "enum": [ "tray", "trolley" ], "title": "Tray or trolley", "type": "string" }, "runner_id": { "format": "uuid", "title": "Who runs the order up", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.guest_check" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.dispatch_room_service:apply" ] } ], "summary": "Dispatch room service", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.dispatch_room_service/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_dispatch_room_service` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.dispatch_room_service:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_dispatch_room_service", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "conveyance": { "enum": [ "tray", "trolley" ], "title": "Tray or trolley", "type": "string" }, "runner_id": { "format": "uuid", "title": "Who runs the order up", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.guest_check" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Dispatch room service (dry-run)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.dispatch_room_service/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_dispatch_room_service`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_dispatch_room_service", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "conveyance": { "enum": [ "tray", "trolley" ], "title": "Tray or trolley", "type": "string" }, "runner_id": { "format": "uuid", "title": "Who runs the order up", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Dispatch room service (dry-run)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.dispatch_room_service/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_dispatch_room_service` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.dispatch_room_service:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_dispatch_room_service", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "conveyance": { "enum": [ "tray", "trolley" ], "title": "Tray or trolley", "type": "string" }, "runner_id": { "format": "uuid", "title": "Who runs the order up", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Dispatch room service (rollup delta)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.dispatch_workflow_step_to_agent/apply": { "post": { "description": "Task an agent installation with a workflow step over the proposal 0022 wire: enqueue one pending `participant_dispatch_attempt` (kind `workflow_step_invocation`) the dispatcher worker signs and POSTs to the installation's `dispatch_endpoint_url`. The payload carries the installation's registry `agent_key` plus the caller-supplied natural-language `task`; completion flows back through the 0022 receiver routes, which advance this step via the internal step-attempt/result actions. The installation must be enabled, dispatch-configured, and — when it carries an `allowed_workflow_keys` allowlist — allowlisted for this run's workflow_key. One in-flight dispatch per step: re-dispatch is rejected while a prior dispatch row is still pending/in-flight/acknowledged. Emits `workflow_step.dispatched_to_agent`.\n\nEffects: modify hospitality.workflow_step_run; create hospitality.participant_dispatch_attempt; link hospitality.link.participant_dispatch_for_workflow_run.", "operationId": "apply_hospitality_action_dispatch_workflow_step_to_agent", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "agent_installation_id": { "format": "uuid", "title": "Enabled, dispatch-configured installation to task", "type": "string", "x-aerandil-references": "hospitality.agent_installation" }, "context": { "additionalProperties": true, "title": "Optional extra context folded into the dispatch payload (JSON object; opaque to the kernel)", "type": "object" }, "task": { "title": "Natural-language task the agent definition runs with", "type": "string" } }, "required": [ "agent_installation_id", "task" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_step_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.participant_dispatch_for_workflow_run" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.workflow_step_run", "hospitality.participant_dispatch_attempt" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.dispatch_workflow_step_to_agent:apply" ] } ], "summary": "Dispatch workflow step to agent", "tags": [ "workflows" ] } }, "/v1/actions/hospitality.action.dispatch_workflow_step_to_agent/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_dispatch_workflow_step_to_agent` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.dispatch_workflow_step_to_agent:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_dispatch_workflow_step_to_agent", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "agent_installation_id": { "format": "uuid", "title": "Enabled, dispatch-configured installation to task", "type": "string", "x-aerandil-references": "hospitality.agent_installation" }, "context": { "additionalProperties": true, "title": "Optional extra context folded into the dispatch payload (JSON object; opaque to the kernel)", "type": "object" }, "task": { "title": "Natural-language task the agent definition runs with", "type": "string" } }, "required": [ "agent_installation_id", "task" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_step_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.participant_dispatch_for_workflow_run" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.workflow_step_run", "hospitality.participant_dispatch_attempt" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Dispatch workflow step to agent (dry-run)", "tags": [ "workflows" ] } }, "/v1/actions/hospitality.action.dispatch_workflow_step_to_agent/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_dispatch_workflow_step_to_agent`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_dispatch_workflow_step_to_agent", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "agent_installation_id": { "format": "uuid", "title": "Enabled, dispatch-configured installation to task", "type": "string", "x-aerandil-references": "hospitality.agent_installation" }, "context": { "additionalProperties": true, "title": "Optional extra context folded into the dispatch payload (JSON object; opaque to the kernel)", "type": "object" }, "task": { "title": "Natural-language task the agent definition runs with", "type": "string" } }, "required": [ "agent_installation_id", "task" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_step_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Dispatch workflow step to agent (dry-run)", "tags": [ "workflows" ] } }, "/v1/actions/hospitality.action.dispatch_workflow_step_to_agent/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_dispatch_workflow_step_to_agent` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.dispatch_workflow_step_to_agent:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_dispatch_workflow_step_to_agent", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "agent_installation_id": { "format": "uuid", "title": "Enabled, dispatch-configured installation to task", "type": "string", "x-aerandil-references": "hospitality.agent_installation" }, "context": { "additionalProperties": true, "title": "Optional extra context folded into the dispatch payload (JSON object; opaque to the kernel)", "type": "object" }, "task": { "title": "Natural-language task the agent definition runs with", "type": "string" } }, "required": [ "agent_installation_id", "task" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_step_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Dispatch workflow step to agent (rollup delta)", "tags": [ "workflows" ] } }, "/v1/actions/hospitality.action.dispose_lost_found_item/apply": { "post": { "description": "Stop keeping a found item: `disposed` (terminal) with when, how (`method`: donated, destroyed, handed to the police, released to the finder, other) and why (`reason` — \"unclaimed past the 90-day hold\"). Disposing of it again is a no-op; a returned item is refused. Emits `lost_found_item.disposed`.\n\nEffects: modify hospitality.lost_found_item.", "operationId": "apply_hospitality_action_dispose_lost_found_item", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "method": { "enum": [ "donated", "destroyed", "handed_to_police", "released_to_finder", "other" ], "title": "What happened to it", "type": "string" }, "reason": { "title": "Why it was not kept any longer", "type": "string" } }, "required": [ "method", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.lost_found_item" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.lost_found_item" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.dispose_lost_found_item:apply" ] } ], "summary": "Dispose of lost & found item", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.dispose_lost_found_item/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_dispose_lost_found_item` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.dispose_lost_found_item:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_dispose_lost_found_item", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "method": { "enum": [ "donated", "destroyed", "handed_to_police", "released_to_finder", "other" ], "title": "What happened to it", "type": "string" }, "reason": { "title": "Why it was not kept any longer", "type": "string" } }, "required": [ "method", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.lost_found_item" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.lost_found_item" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Dispose of lost & found item (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.dispose_lost_found_item/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_dispose_lost_found_item`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_dispose_lost_found_item", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "method": { "enum": [ "donated", "destroyed", "handed_to_police", "released_to_finder", "other" ], "title": "What happened to it", "type": "string" }, "reason": { "title": "Why it was not kept any longer", "type": "string" } }, "required": [ "method", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.lost_found_item" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Dispose of lost & found item (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.dispose_lost_found_item/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_dispose_lost_found_item` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.dispose_lost_found_item:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_dispose_lost_found_item", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "method": { "enum": [ "donated", "destroyed", "handed_to_police", "released_to_finder", "other" ], "title": "What happened to it", "type": "string" }, "reason": { "title": "Why it was not kept any longer", "type": "string" } }, "required": [ "method", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.lost_found_item" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Dispose of lost & found item (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.draft_banquet_event_order/apply": { "post": { "description": "Open the banquet event order for an event: a draft at revision 0 under the banquet outlet its charges will post through, priced in one currency, with the setup, service, AV and billing notes. An explicit `folio_id` fixes where the charges go; without one, a group's event posts to its block's master folio. One order per event; a cancelled event refuses.\n\nEffects: create hospitality.banquet_event_order; link hospitality.link.function_event_has_order; link hospitality.link.banquet_order_at_outlet; link hospitality.link.banquet_order_posts_to_folio.", "operationId": "apply_hospitality_action_draft_banquet_event_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "av_notes": { "title": "Audiovisual notes", "type": "string" }, "billing_instructions": { "title": "How the client pays", "type": "string" }, "currency": { "format": "iso-4217", "title": "Currency every line is priced in", "type": "string" }, "folio_id": { "format": "uuid", "title": "The folio the charges post to", "type": "string", "x-aerandil-references": "hospitality.folio" }, "outlet_id": { "format": "uuid", "title": "The banquet revenue centre the charges post under", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "service_charge_rate": { "format": "decimal", "title": "Service charge on food and beverage lines (0.125 = 12.5%)", "type": "string" }, "service_notes": { "title": "Service notes: the run of show", "type": "string" }, "setup_notes": { "title": "Setup notes", "type": "string" } }, "required": [ "outlet_id", "currency" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_event" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.function_event_has_order", "hospitality.link.banquet_order_at_outlet", "hospitality.link.banquet_order_posts_to_folio" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.banquet_event_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.draft_banquet_event_order:apply" ] } ], "summary": "Draft banquet event order", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.draft_banquet_event_order/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_draft_banquet_event_order` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.draft_banquet_event_order:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_draft_banquet_event_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "av_notes": { "title": "Audiovisual notes", "type": "string" }, "billing_instructions": { "title": "How the client pays", "type": "string" }, "currency": { "format": "iso-4217", "title": "Currency every line is priced in", "type": "string" }, "folio_id": { "format": "uuid", "title": "The folio the charges post to", "type": "string", "x-aerandil-references": "hospitality.folio" }, "outlet_id": { "format": "uuid", "title": "The banquet revenue centre the charges post under", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "service_charge_rate": { "format": "decimal", "title": "Service charge on food and beverage lines (0.125 = 12.5%)", "type": "string" }, "service_notes": { "title": "Service notes: the run of show", "type": "string" }, "setup_notes": { "title": "Setup notes", "type": "string" } }, "required": [ "outlet_id", "currency" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_event" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.function_event_has_order", "hospitality.link.banquet_order_at_outlet", "hospitality.link.banquet_order_posts_to_folio" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.banquet_event_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Draft banquet event order (dry-run)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.draft_banquet_event_order/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_draft_banquet_event_order`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_draft_banquet_event_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "av_notes": { "title": "Audiovisual notes", "type": "string" }, "billing_instructions": { "title": "How the client pays", "type": "string" }, "currency": { "format": "iso-4217", "title": "Currency every line is priced in", "type": "string" }, "folio_id": { "format": "uuid", "title": "The folio the charges post to", "type": "string", "x-aerandil-references": "hospitality.folio" }, "outlet_id": { "format": "uuid", "title": "The banquet revenue centre the charges post under", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "service_charge_rate": { "format": "decimal", "title": "Service charge on food and beverage lines (0.125 = 12.5%)", "type": "string" }, "service_notes": { "title": "Service notes: the run of show", "type": "string" }, "setup_notes": { "title": "Setup notes", "type": "string" } }, "required": [ "outlet_id", "currency" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_event" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Draft banquet event order (dry-run)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.draft_banquet_event_order/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_draft_banquet_event_order` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.draft_banquet_event_order:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_draft_banquet_event_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "av_notes": { "title": "Audiovisual notes", "type": "string" }, "billing_instructions": { "title": "How the client pays", "type": "string" }, "currency": { "format": "iso-4217", "title": "Currency every line is priced in", "type": "string" }, "folio_id": { "format": "uuid", "title": "The folio the charges post to", "type": "string", "x-aerandil-references": "hospitality.folio" }, "outlet_id": { "format": "uuid", "title": "The banquet revenue centre the charges post under", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "service_charge_rate": { "format": "decimal", "title": "Service charge on food and beverage lines (0.125 = 12.5%)", "type": "string" }, "service_notes": { "title": "Service notes: the run of show", "type": "string" }, "setup_notes": { "title": "Setup notes", "type": "string" } }, "required": [ "outlet_id", "currency" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_event" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Draft banquet event order (rollup delta)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.enable_agent_installation/apply": { "post": { "description": "Enable a reviewed registry entry for a tenant / property scope. Validators (commit 11): `agent_registry_approved_before_install`, `agent_installation_scopes_subset_declared`, `agent_installation_no_broad_catch_all_scope`, `agent_installation_no_internal_workflow_scope`, `agent_installation_scope_ref_coherent`, `agent_installation_unique_per_scope_entry`, `agent_installation_scope_within_tenancy`, `agent_installation_high_risk_requires_policy`, `credential_reference_no_secret_material`.\n\nEffects: create hospitality.agent_installation; link hospitality.link.agent_installation_for_registry_entry.", "operationId": "apply_hospitality_action_enable_agent_installation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allowed_workflow_keys": { "items": { "type": "string" }, "title": "Optional workflow-key allowlist", "type": "array" }, "approval_policy": { "title": "Gates required for high-risk steps" }, "auth_mode": { "enum": [ "none", "oauth_client_credentials", "oauth_delegated", "api_key_reference", "jwt_exchange", "mcp_oauth" ], "title": "How the installation authenticates at call time", "type": "string" }, "credential_reference": { "title": "Opaque pointer into an external secret manager", "type": "string" }, "enabled_action_scopes": { "items": { "type": "string" }, "title": "Subset of registry entry declared action scopes", "type": "array" }, "enabled_data_classes": { "items": { "enum": [ "public", "operational", "guest_pii", "staff_pii", "payment_metadata", "regulated_health", "secrets" ], "type": "string" }, "title": "Subset of registry entry declared data classes", "type": "array" }, "enabled_function_scopes": { "items": { "type": "string" }, "title": "Subset of registry entry declared function scopes", "type": "array" }, "enabled_read_scopes": { "items": { "type": "string" }, "title": "Subset of registry entry declared read scopes; defaults to all of them", "type": "array" }, "enablement_note": { "title": "Free-text note", "type": "string" }, "expires_at": { "format": "date-time", "title": "Optional time-bound install", "type": "string" }, "installed_scope": { "enum": [ "tenant", "brand", "portfolio", "property", "venue" ], "title": "Tenancy scope this installation grants access at", "type": "string" }, "installed_scope_ref_object_id": { "title": "Required when installed_scope != tenant", "type": "string" }, "installed_scope_ref_object_type": { "title": "Required when installed_scope != tenant", "type": "string" } }, "required": [ "installed_scope", "auth_mode" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_registry_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.agent_installation_for_registry_entry" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.agent_installation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.enable_agent_installation:apply" ] } ], "summary": "Enable agent installation", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.enable_agent_installation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_enable_agent_installation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.enable_agent_installation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_enable_agent_installation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allowed_workflow_keys": { "items": { "type": "string" }, "title": "Optional workflow-key allowlist", "type": "array" }, "approval_policy": { "title": "Gates required for high-risk steps" }, "auth_mode": { "enum": [ "none", "oauth_client_credentials", "oauth_delegated", "api_key_reference", "jwt_exchange", "mcp_oauth" ], "title": "How the installation authenticates at call time", "type": "string" }, "credential_reference": { "title": "Opaque pointer into an external secret manager", "type": "string" }, "enabled_action_scopes": { "items": { "type": "string" }, "title": "Subset of registry entry declared action scopes", "type": "array" }, "enabled_data_classes": { "items": { "enum": [ "public", "operational", "guest_pii", "staff_pii", "payment_metadata", "regulated_health", "secrets" ], "type": "string" }, "title": "Subset of registry entry declared data classes", "type": "array" }, "enabled_function_scopes": { "items": { "type": "string" }, "title": "Subset of registry entry declared function scopes", "type": "array" }, "enabled_read_scopes": { "items": { "type": "string" }, "title": "Subset of registry entry declared read scopes; defaults to all of them", "type": "array" }, "enablement_note": { "title": "Free-text note", "type": "string" }, "expires_at": { "format": "date-time", "title": "Optional time-bound install", "type": "string" }, "installed_scope": { "enum": [ "tenant", "brand", "portfolio", "property", "venue" ], "title": "Tenancy scope this installation grants access at", "type": "string" }, "installed_scope_ref_object_id": { "title": "Required when installed_scope != tenant", "type": "string" }, "installed_scope_ref_object_type": { "title": "Required when installed_scope != tenant", "type": "string" } }, "required": [ "installed_scope", "auth_mode" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_registry_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.agent_installation_for_registry_entry" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.agent_installation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Enable agent installation (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.enable_agent_installation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_enable_agent_installation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_enable_agent_installation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allowed_workflow_keys": { "items": { "type": "string" }, "title": "Optional workflow-key allowlist", "type": "array" }, "approval_policy": { "title": "Gates required for high-risk steps" }, "auth_mode": { "enum": [ "none", "oauth_client_credentials", "oauth_delegated", "api_key_reference", "jwt_exchange", "mcp_oauth" ], "title": "How the installation authenticates at call time", "type": "string" }, "credential_reference": { "title": "Opaque pointer into an external secret manager", "type": "string" }, "enabled_action_scopes": { "items": { "type": "string" }, "title": "Subset of registry entry declared action scopes", "type": "array" }, "enabled_data_classes": { "items": { "enum": [ "public", "operational", "guest_pii", "staff_pii", "payment_metadata", "regulated_health", "secrets" ], "type": "string" }, "title": "Subset of registry entry declared data classes", "type": "array" }, "enabled_function_scopes": { "items": { "type": "string" }, "title": "Subset of registry entry declared function scopes", "type": "array" }, "enabled_read_scopes": { "items": { "type": "string" }, "title": "Subset of registry entry declared read scopes; defaults to all of them", "type": "array" }, "enablement_note": { "title": "Free-text note", "type": "string" }, "expires_at": { "format": "date-time", "title": "Optional time-bound install", "type": "string" }, "installed_scope": { "enum": [ "tenant", "brand", "portfolio", "property", "venue" ], "title": "Tenancy scope this installation grants access at", "type": "string" }, "installed_scope_ref_object_id": { "title": "Required when installed_scope != tenant", "type": "string" }, "installed_scope_ref_object_type": { "title": "Required when installed_scope != tenant", "type": "string" } }, "required": [ "installed_scope", "auth_mode" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_registry_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Enable agent installation (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.enable_agent_installation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_enable_agent_installation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.enable_agent_installation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_enable_agent_installation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allowed_workflow_keys": { "items": { "type": "string" }, "title": "Optional workflow-key allowlist", "type": "array" }, "approval_policy": { "title": "Gates required for high-risk steps" }, "auth_mode": { "enum": [ "none", "oauth_client_credentials", "oauth_delegated", "api_key_reference", "jwt_exchange", "mcp_oauth" ], "title": "How the installation authenticates at call time", "type": "string" }, "credential_reference": { "title": "Opaque pointer into an external secret manager", "type": "string" }, "enabled_action_scopes": { "items": { "type": "string" }, "title": "Subset of registry entry declared action scopes", "type": "array" }, "enabled_data_classes": { "items": { "enum": [ "public", "operational", "guest_pii", "staff_pii", "payment_metadata", "regulated_health", "secrets" ], "type": "string" }, "title": "Subset of registry entry declared data classes", "type": "array" }, "enabled_function_scopes": { "items": { "type": "string" }, "title": "Subset of registry entry declared function scopes", "type": "array" }, "enabled_read_scopes": { "items": { "type": "string" }, "title": "Subset of registry entry declared read scopes; defaults to all of them", "type": "array" }, "enablement_note": { "title": "Free-text note", "type": "string" }, "expires_at": { "format": "date-time", "title": "Optional time-bound install", "type": "string" }, "installed_scope": { "enum": [ "tenant", "brand", "portfolio", "property", "venue" ], "title": "Tenancy scope this installation grants access at", "type": "string" }, "installed_scope_ref_object_id": { "title": "Required when installed_scope != tenant", "type": "string" }, "installed_scope_ref_object_type": { "title": "Required when installed_scope != tenant", "type": "string" } }, "required": [ "installed_scope", "auth_mode" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_registry_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Enable agent installation (rollup delta)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.end_deposit_policy/apply": { "post": { "description": "Close (or shorten) a deposit policy's effective window: sets `effective_to`. Refuses a date before the policy's effective_from, and refuses a window that would overlap a later policy in the same code's succession. A gap in the timeline is legal — a no-deposit window is a legitimate commercial posture, and the authoring event records who opened it.\n\nEffects: modify hospitality.deposit_policy.", "operationId": "apply_hospitality_action_end_deposit_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_to": { "format": "date", "title": "Last booking date the policy applies (inclusive)", "type": "string" } }, "required": [ "effective_to" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.deposit_policy" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.deposit_policy" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.end_deposit_policy:apply" ] } ], "summary": "End deposit policy", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.end_deposit_policy/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_end_deposit_policy` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.end_deposit_policy:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_end_deposit_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_to": { "format": "date", "title": "Last booking date the policy applies (inclusive)", "type": "string" } }, "required": [ "effective_to" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.deposit_policy" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.deposit_policy" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview End deposit policy (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.end_deposit_policy/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_end_deposit_policy`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_end_deposit_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_to": { "format": "date", "title": "Last booking date the policy applies (inclusive)", "type": "string" } }, "required": [ "effective_to" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.deposit_policy" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate End deposit policy (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.end_deposit_policy/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_end_deposit_policy` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.end_deposit_policy:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_end_deposit_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_to": { "format": "date", "title": "Last booking date the policy applies (inclusive)", "type": "string" } }, "required": [ "effective_to" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.deposit_policy" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if End deposit policy (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.end_residency/apply": { "post": { "description": "Close an active venue_residency link by setting `effective_to`. Supersedes-not-mutates per design-spec §B.2 — the historical residency stays queryable via `as_of` lookups so an operator can audit which chef ran the venue during a given season.\n\nEffects: unlink hospitality.link.venue_residency.", "operationId": "apply_hospitality_action_end_residency", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "company_id": { "format": "uuid", "title": "Partner company whose residency ends", "type": "string", "x-aerandil-references": "hospitality.company" }, "effective_to": { "format": "date-time", "title": "Residency end", "type": "string" } }, "required": [ "company_id", "effective_to" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.venue_residency" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.end_residency:apply" ] } ], "summary": "End residency", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.end_residency/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_end_residency` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.end_residency:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_end_residency", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "company_id": { "format": "uuid", "title": "Partner company whose residency ends", "type": "string", "x-aerandil-references": "hospitality.company" }, "effective_to": { "format": "date-time", "title": "Residency end", "type": "string" } }, "required": [ "company_id", "effective_to" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.venue_residency" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview End residency (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.end_residency/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_end_residency`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_end_residency", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "company_id": { "format": "uuid", "title": "Partner company whose residency ends", "type": "string", "x-aerandil-references": "hospitality.company" }, "effective_to": { "format": "date-time", "title": "Residency end", "type": "string" } }, "required": [ "company_id", "effective_to" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate End residency (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.end_residency/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_end_residency` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.end_residency:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_end_residency", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "company_id": { "format": "uuid", "title": "Partner company whose residency ends", "type": "string", "x-aerandil-references": "hospitality.company" }, "effective_to": { "format": "date-time", "title": "Residency end", "type": "string" } }, "required": [ "company_id", "effective_to" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if End residency (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.end_tax_rule/apply": { "post": { "description": "Close (or shorten) a tax rule's effective window: sets `effective_to`. Refuses a date before the rule's effective_from, and refuses a window that would overlap a later rule in the same code's succession. A gap in the timeline is legal — an untaxed window is a legitimate jurisdictional fact (a suspended levy), and the authoring event records who opened it.\n\nEffects: modify hospitality.tax_rule.", "operationId": "apply_hospitality_action_end_tax_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_to": { "format": "date", "title": "Last business date the rule applies (inclusive)", "type": "string" } }, "required": [ "effective_to" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.tax_rule" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.tax_rule" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.end_tax_rule:apply" ] } ], "summary": "End tax rule", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.end_tax_rule/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_end_tax_rule` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.end_tax_rule:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_end_tax_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_to": { "format": "date", "title": "Last business date the rule applies (inclusive)", "type": "string" } }, "required": [ "effective_to" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.tax_rule" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.tax_rule" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview End tax rule (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.end_tax_rule/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_end_tax_rule`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_end_tax_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_to": { "format": "date", "title": "Last business date the rule applies (inclusive)", "type": "string" } }, "required": [ "effective_to" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.tax_rule" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate End tax rule (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.end_tax_rule/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_end_tax_rule` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.end_tax_rule:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_end_tax_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_to": { "format": "date", "title": "Last business date the rule applies (inclusive)", "type": "string" } }, "required": [ "effective_to" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.tax_rule" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if End tax rule (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.enrol_member/apply": { "post": { "description": "Open a new membership: create the account, mint the primary `membership` row, attach to the entry tier, and optionally create a subscription + initiation. The account is the durable identity that survives every subsequent transition; dependent enrolment uses `add_dependent_membership`. By default the account id is engine-minted; pass `account_id` to re-use a caller-held id (the PMS-migration shape).\n\nEffects: create hospitality.membership_account; create hospitality.membership; link hospitality.link.membership_account_has_membership; link hospitality.link.membership_for_person; link hospitality.link.membership_at_tier.", "operationId": "apply_hospitality_action_enrol_member", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "account_id": { "title": "Caller-supplied account id (UUID string; engine-mints when omitted)", "type": "string" }, "effective_from": { "format": "date-time", "title": "Tier attachment start", "type": "string" }, "enrolment_kind": { "enum": [ "direct_enrolment", "inherited", "gifted", "reciprocity", "corporate_seat" ], "title": "How the membership came to exist", "type": "string" }, "home_property_id": { "format": "uuid", "title": "Home property", "type": "string", "x-aerandil-references": "hospitality.property" }, "initial_tier_id": { "format": "uuid", "title": "Initial tier", "type": "string", "x-aerandil-references": "hospitality.membership_tier" }, "member_number": { "title": "Operator-side member number", "type": "string" }, "primary_person_id": { "format": "uuid", "title": "Primary member (typed person reference)", "type": "string", "x-aerandil-references": "hospitality.person" } }, "required": [ "member_number", "initial_tier_id", "enrolment_kind", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.membership_account_has_membership", "hospitality.link.membership_for_person", "hospitality.link.membership_at_tier" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.membership_account", "hospitality.membership" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.enrol_member:apply" ] } ], "summary": "Enrol member", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.enrol_member/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_enrol_member` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.enrol_member:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_enrol_member", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "account_id": { "title": "Caller-supplied account id (UUID string; engine-mints when omitted)", "type": "string" }, "effective_from": { "format": "date-time", "title": "Tier attachment start", "type": "string" }, "enrolment_kind": { "enum": [ "direct_enrolment", "inherited", "gifted", "reciprocity", "corporate_seat" ], "title": "How the membership came to exist", "type": "string" }, "home_property_id": { "format": "uuid", "title": "Home property", "type": "string", "x-aerandil-references": "hospitality.property" }, "initial_tier_id": { "format": "uuid", "title": "Initial tier", "type": "string", "x-aerandil-references": "hospitality.membership_tier" }, "member_number": { "title": "Operator-side member number", "type": "string" }, "primary_person_id": { "format": "uuid", "title": "Primary member (typed person reference)", "type": "string", "x-aerandil-references": "hospitality.person" } }, "required": [ "member_number", "initial_tier_id", "enrolment_kind", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.membership_account_has_membership", "hospitality.link.membership_for_person", "hospitality.link.membership_at_tier" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.membership_account", "hospitality.membership" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Enrol member (dry-run)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.enrol_member/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_enrol_member`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_enrol_member", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "account_id": { "title": "Caller-supplied account id (UUID string; engine-mints when omitted)", "type": "string" }, "effective_from": { "format": "date-time", "title": "Tier attachment start", "type": "string" }, "enrolment_kind": { "enum": [ "direct_enrolment", "inherited", "gifted", "reciprocity", "corporate_seat" ], "title": "How the membership came to exist", "type": "string" }, "home_property_id": { "format": "uuid", "title": "Home property", "type": "string", "x-aerandil-references": "hospitality.property" }, "initial_tier_id": { "format": "uuid", "title": "Initial tier", "type": "string", "x-aerandil-references": "hospitality.membership_tier" }, "member_number": { "title": "Operator-side member number", "type": "string" }, "primary_person_id": { "format": "uuid", "title": "Primary member (typed person reference)", "type": "string", "x-aerandil-references": "hospitality.person" } }, "required": [ "member_number", "initial_tier_id", "enrolment_kind", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Enrol member (dry-run)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.enrol_member/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_enrol_member` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.enrol_member:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_enrol_member", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "account_id": { "title": "Caller-supplied account id (UUID string; engine-mints when omitted)", "type": "string" }, "effective_from": { "format": "date-time", "title": "Tier attachment start", "type": "string" }, "enrolment_kind": { "enum": [ "direct_enrolment", "inherited", "gifted", "reciprocity", "corporate_seat" ], "title": "How the membership came to exist", "type": "string" }, "home_property_id": { "format": "uuid", "title": "Home property", "type": "string", "x-aerandil-references": "hospitality.property" }, "initial_tier_id": { "format": "uuid", "title": "Initial tier", "type": "string", "x-aerandil-references": "hospitality.membership_tier" }, "member_number": { "title": "Operator-side member number", "type": "string" }, "primary_person_id": { "format": "uuid", "title": "Primary member (typed person reference)", "type": "string", "x-aerandil-references": "hospitality.person" } }, "required": [ "member_number", "initial_tier_id", "enrolment_kind", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Enrol member (rollup delta)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.enrol_property_in_program/apply": { "post": { "description": "Link a loyalty_program to the target property via the M:N `loyalty_program_at_property` link with effective dates. A property can run multiple programs simultaneously (a soft-brand collection property running both the parent chain's program and the soft-brand's recognition layer; an SLH-Hilton partnership property running SLH INVITED + Hilton Honors). The temporal link tracks the participation window so programs can be left and rejoined without losing history.\n\nEffects: link hospitality.link.loyalty_program_at_property.", "operationId": "apply_hospitality_action_enrol_property_in_program", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date-time", "title": "Participation start", "type": "string" }, "effective_to": { "format": "date-time", "title": "Participation end (null when ongoing)", "type": "string" }, "program_id": { "format": "uuid", "title": "Loyalty program", "type": "string", "x-aerandil-references": "hospitality.loyalty_program" } }, "required": [ "program_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.loyalty_program_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.enrol_property_in_program:apply" ] } ], "summary": "Enrol property in loyalty program", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.enrol_property_in_program/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_enrol_property_in_program` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.enrol_property_in_program:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_enrol_property_in_program", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date-time", "title": "Participation start", "type": "string" }, "effective_to": { "format": "date-time", "title": "Participation end (null when ongoing)", "type": "string" }, "program_id": { "format": "uuid", "title": "Loyalty program", "type": "string", "x-aerandil-references": "hospitality.loyalty_program" } }, "required": [ "program_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.loyalty_program_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Enrol property in loyalty program (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.enrol_property_in_program/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_enrol_property_in_program`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_enrol_property_in_program", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date-time", "title": "Participation start", "type": "string" }, "effective_to": { "format": "date-time", "title": "Participation end (null when ongoing)", "type": "string" }, "program_id": { "format": "uuid", "title": "Loyalty program", "type": "string", "x-aerandil-references": "hospitality.loyalty_program" } }, "required": [ "program_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Enrol property in loyalty program (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.enrol_property_in_program/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_enrol_property_in_program` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.enrol_property_in_program:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_enrol_property_in_program", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date-time", "title": "Participation start", "type": "string" }, "effective_to": { "format": "date-time", "title": "Participation end (null when ongoing)", "type": "string" }, "program_id": { "format": "uuid", "title": "Loyalty program", "type": "string", "x-aerandil-references": "hospitality.loyalty_program" } }, "required": [ "program_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Enrol property in loyalty program (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.enroll_federated_participant/apply": { "post": { "description": "Create or activate a participant opt-in record. Validates program status, compatible analysis kinds, legal basis / DPA / consent references, and (when execution mode is agent_installation) the enabled agent installation. Validators (commit 5): `participation_active_requires_legal_basis_and_reference`, `participation_consent_requires_consent_policy_reference`, `participation_active_requires_compatible_analysis_kinds`, `participation_agent_installation_required_when_execution_mode_is_agent`, `participation_cross_tenant_requires_dpa_or_review_waiver`.\n\nEffects: create hospitality.federated_participation; link hospitality.link.federated_participation_in_program; link hospitality.link.federated_local_runner_agent_installation; link hospitality.link.federated_participation_for_property; link hospitality.link.federated_participation_for_venue.", "operationId": "apply_hospitality_action_enroll_federated_participant", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "activate": { "title": "True to activate; false leaves status = reviewing", "type": "boolean" }, "agent_installation_id": { "title": "Required when execution mode is agent_installation", "type": "string" }, "allowed_analysis_kinds": { "items": { "enum": [ "federated_analytics", "federated_learning", "private_set_intersection", "clean_room_query", "benchmark_export" ], "type": "string" }, "title": "Participant-allowed analysis kinds", "type": "array" }, "consent_policy_reference": { "title": "Required if consent is the basis", "type": "string" }, "contribution_weight_cap": { "format": "decimal", "title": "Participant-specific cap stricter than definition", "type": "string" }, "credential_reference": { "title": "Opaque pointer; no secret material", "type": "string" }, "dpa_reference": { "title": "Required for cross-tenant programs", "type": "string" }, "excluded_field_classes": { "items": { "type": "string" }, "title": "Additional local privacy exclusions", "type": "array" }, "excluded_object_types": { "items": { "type": "string" }, "title": "Tenant-specific exclusions", "type": "array" }, "legal_basis_kind": { "enum": [ "contract", "legitimate_interest", "consent", "public_task", "not_personal_data", "other_reviewed" ], "title": "Legal basis kind", "type": "string" }, "legal_basis_reference": { "title": "Required except not_personal_data with reviewer note", "type": "string" }, "local_execution_mode": { "enum": [ "operator_runner", "agent_installation", "hosted_connector", "third_party_clean_room" ], "title": "operator_runner / agent_installation / hosted_connector / third_party_clean_room", "type": "string" }, "output_access_level": { "enum": [ "none", "aggregate_only", "participant_benchmark", "model_consumer" ], "title": "Output-access tier", "type": "string" }, "participant_object_ref": { "title": "Property / venue id when scope is not tenant", "type": "string" }, "participant_scope": { "enum": [ "tenant", "property", "portfolio", "venue" ], "title": "tenant / property / portfolio / venue", "type": "string" } }, "required": [ "participant_scope", "legal_basis_kind", "allowed_analysis_kinds", "local_execution_mode", "output_access_level" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_intelligence_program" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.federated_participation_in_program", "hospitality.link.federated_local_runner_agent_installation", "hospitality.link.federated_participation_for_property", "hospitality.link.federated_participation_for_venue" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.federated_participation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.enroll_federated_participant:apply" ] } ], "summary": "Enroll federated participant", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.enroll_federated_participant/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_enroll_federated_participant` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.enroll_federated_participant:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_enroll_federated_participant", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "activate": { "title": "True to activate; false leaves status = reviewing", "type": "boolean" }, "agent_installation_id": { "title": "Required when execution mode is agent_installation", "type": "string" }, "allowed_analysis_kinds": { "items": { "enum": [ "federated_analytics", "federated_learning", "private_set_intersection", "clean_room_query", "benchmark_export" ], "type": "string" }, "title": "Participant-allowed analysis kinds", "type": "array" }, "consent_policy_reference": { "title": "Required if consent is the basis", "type": "string" }, "contribution_weight_cap": { "format": "decimal", "title": "Participant-specific cap stricter than definition", "type": "string" }, "credential_reference": { "title": "Opaque pointer; no secret material", "type": "string" }, "dpa_reference": { "title": "Required for cross-tenant programs", "type": "string" }, "excluded_field_classes": { "items": { "type": "string" }, "title": "Additional local privacy exclusions", "type": "array" }, "excluded_object_types": { "items": { "type": "string" }, "title": "Tenant-specific exclusions", "type": "array" }, "legal_basis_kind": { "enum": [ "contract", "legitimate_interest", "consent", "public_task", "not_personal_data", "other_reviewed" ], "title": "Legal basis kind", "type": "string" }, "legal_basis_reference": { "title": "Required except not_personal_data with reviewer note", "type": "string" }, "local_execution_mode": { "enum": [ "operator_runner", "agent_installation", "hosted_connector", "third_party_clean_room" ], "title": "operator_runner / agent_installation / hosted_connector / third_party_clean_room", "type": "string" }, "output_access_level": { "enum": [ "none", "aggregate_only", "participant_benchmark", "model_consumer" ], "title": "Output-access tier", "type": "string" }, "participant_object_ref": { "title": "Property / venue id when scope is not tenant", "type": "string" }, "participant_scope": { "enum": [ "tenant", "property", "portfolio", "venue" ], "title": "tenant / property / portfolio / venue", "type": "string" } }, "required": [ "participant_scope", "legal_basis_kind", "allowed_analysis_kinds", "local_execution_mode", "output_access_level" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_intelligence_program" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.federated_participation_in_program", "hospitality.link.federated_local_runner_agent_installation", "hospitality.link.federated_participation_for_property", "hospitality.link.federated_participation_for_venue" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.federated_participation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Enroll federated participant (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.enroll_federated_participant/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_enroll_federated_participant`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_enroll_federated_participant", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "activate": { "title": "True to activate; false leaves status = reviewing", "type": "boolean" }, "agent_installation_id": { "title": "Required when execution mode is agent_installation", "type": "string" }, "allowed_analysis_kinds": { "items": { "enum": [ "federated_analytics", "federated_learning", "private_set_intersection", "clean_room_query", "benchmark_export" ], "type": "string" }, "title": "Participant-allowed analysis kinds", "type": "array" }, "consent_policy_reference": { "title": "Required if consent is the basis", "type": "string" }, "contribution_weight_cap": { "format": "decimal", "title": "Participant-specific cap stricter than definition", "type": "string" }, "credential_reference": { "title": "Opaque pointer; no secret material", "type": "string" }, "dpa_reference": { "title": "Required for cross-tenant programs", "type": "string" }, "excluded_field_classes": { "items": { "type": "string" }, "title": "Additional local privacy exclusions", "type": "array" }, "excluded_object_types": { "items": { "type": "string" }, "title": "Tenant-specific exclusions", "type": "array" }, "legal_basis_kind": { "enum": [ "contract", "legitimate_interest", "consent", "public_task", "not_personal_data", "other_reviewed" ], "title": "Legal basis kind", "type": "string" }, "legal_basis_reference": { "title": "Required except not_personal_data with reviewer note", "type": "string" }, "local_execution_mode": { "enum": [ "operator_runner", "agent_installation", "hosted_connector", "third_party_clean_room" ], "title": "operator_runner / agent_installation / hosted_connector / third_party_clean_room", "type": "string" }, "output_access_level": { "enum": [ "none", "aggregate_only", "participant_benchmark", "model_consumer" ], "title": "Output-access tier", "type": "string" }, "participant_object_ref": { "title": "Property / venue id when scope is not tenant", "type": "string" }, "participant_scope": { "enum": [ "tenant", "property", "portfolio", "venue" ], "title": "tenant / property / portfolio / venue", "type": "string" } }, "required": [ "participant_scope", "legal_basis_kind", "allowed_analysis_kinds", "local_execution_mode", "output_access_level" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_intelligence_program" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Enroll federated participant (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.enroll_federated_participant/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_enroll_federated_participant` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.enroll_federated_participant:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_enroll_federated_participant", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "activate": { "title": "True to activate; false leaves status = reviewing", "type": "boolean" }, "agent_installation_id": { "title": "Required when execution mode is agent_installation", "type": "string" }, "allowed_analysis_kinds": { "items": { "enum": [ "federated_analytics", "federated_learning", "private_set_intersection", "clean_room_query", "benchmark_export" ], "type": "string" }, "title": "Participant-allowed analysis kinds", "type": "array" }, "consent_policy_reference": { "title": "Required if consent is the basis", "type": "string" }, "contribution_weight_cap": { "format": "decimal", "title": "Participant-specific cap stricter than definition", "type": "string" }, "credential_reference": { "title": "Opaque pointer; no secret material", "type": "string" }, "dpa_reference": { "title": "Required for cross-tenant programs", "type": "string" }, "excluded_field_classes": { "items": { "type": "string" }, "title": "Additional local privacy exclusions", "type": "array" }, "excluded_object_types": { "items": { "type": "string" }, "title": "Tenant-specific exclusions", "type": "array" }, "legal_basis_kind": { "enum": [ "contract", "legitimate_interest", "consent", "public_task", "not_personal_data", "other_reviewed" ], "title": "Legal basis kind", "type": "string" }, "legal_basis_reference": { "title": "Required except not_personal_data with reviewer note", "type": "string" }, "local_execution_mode": { "enum": [ "operator_runner", "agent_installation", "hosted_connector", "third_party_clean_room" ], "title": "operator_runner / agent_installation / hosted_connector / third_party_clean_room", "type": "string" }, "output_access_level": { "enum": [ "none", "aggregate_only", "participant_benchmark", "model_consumer" ], "title": "Output-access tier", "type": "string" }, "participant_object_ref": { "title": "Property / venue id when scope is not tenant", "type": "string" }, "participant_scope": { "enum": [ "tenant", "property", "portfolio", "venue" ], "title": "tenant / property / portfolio / venue", "type": "string" } }, "required": [ "participant_scope", "legal_basis_kind", "allowed_analysis_kinds", "local_execution_mode", "output_access_level" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_intelligence_program" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Enroll federated participant (rollup delta)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.escalate_via_fraud_assessment/apply": { "post": { "description": "Escalate a suggested fraud_risk_assessment to the chargeback- defence team or risk analyst with structured handoff. Transitions `decision_status` to `escalated`; sets `escalation_reason`; optionally links to a named staff_member.\n\nEffects: modify hospitality.fraud_risk_assessment; link hospitality.link.fraud_assessment_escalated_to_staff_member.", "operationId": "apply_hospitality_action_escalate_via_fraud_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "escalation_reason": { "enum": [ "low_confidence", "policy_block", "high_value", "chargeback_history_match", "watchlist_hit", "kyc_failure", "three_ds_failure", "manual_review_required", "vendor_uncertainty", "regulatory_review", "operator_override" ], "title": "Reason for escalation", "type": "string" }, "escalation_target_staff_id": { "title": "Optional named staff member to route to", "type": "string" } }, "required": [ "escalation_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fraud_risk_assessment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.fraud_assessment_escalated_to_staff_member" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.fraud_risk_assessment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.escalate_via_fraud_assessment:apply" ] } ], "summary": "Escalate via fraud assessment", "tags": [ "fraud_detection" ] } }, "/v1/actions/hospitality.action.escalate_via_fraud_assessment/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_escalate_via_fraud_assessment` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.escalate_via_fraud_assessment:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_escalate_via_fraud_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "escalation_reason": { "enum": [ "low_confidence", "policy_block", "high_value", "chargeback_history_match", "watchlist_hit", "kyc_failure", "three_ds_failure", "manual_review_required", "vendor_uncertainty", "regulatory_review", "operator_override" ], "title": "Reason for escalation", "type": "string" }, "escalation_target_staff_id": { "title": "Optional named staff member to route to", "type": "string" } }, "required": [ "escalation_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fraud_risk_assessment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.fraud_assessment_escalated_to_staff_member" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.fraud_risk_assessment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Escalate via fraud assessment (dry-run)", "tags": [ "fraud_detection" ] } }, "/v1/actions/hospitality.action.escalate_via_fraud_assessment/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_escalate_via_fraud_assessment`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_escalate_via_fraud_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "escalation_reason": { "enum": [ "low_confidence", "policy_block", "high_value", "chargeback_history_match", "watchlist_hit", "kyc_failure", "three_ds_failure", "manual_review_required", "vendor_uncertainty", "regulatory_review", "operator_override" ], "title": "Reason for escalation", "type": "string" }, "escalation_target_staff_id": { "title": "Optional named staff member to route to", "type": "string" } }, "required": [ "escalation_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fraud_risk_assessment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Escalate via fraud assessment (dry-run)", "tags": [ "fraud_detection" ] } }, "/v1/actions/hospitality.action.escalate_via_fraud_assessment/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_escalate_via_fraud_assessment` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.escalate_via_fraud_assessment:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_escalate_via_fraud_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "escalation_reason": { "enum": [ "low_confidence", "policy_block", "high_value", "chargeback_history_match", "watchlist_hit", "kyc_failure", "three_ds_failure", "manual_review_required", "vendor_uncertainty", "regulatory_review", "operator_override" ], "title": "Reason for escalation", "type": "string" }, "escalation_target_staff_id": { "title": "Optional named staff member to route to", "type": "string" } }, "required": [ "escalation_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fraud_risk_assessment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Escalate via fraud assessment (rollup delta)", "tags": [ "fraud_detection" ] } }, "/v1/actions/hospitality.action.escalate_via_pattern_assessment/apply": { "post": { "description": "Escalate a suggested service_recovery_pattern to a human decision-maker rather than applying or rejecting it directly, optionally routing to a named staff member.\n\nEffects: modify hospitality.service_recovery_pattern; modify hospitality.recovery_pattern_detection_run; link hospitality.link.pattern_escalated_to_staff_member.", "operationId": "apply_hospitality_action_escalate_via_pattern_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "escalation_reason": { "enum": [ "high_severity", "capital_expenditure_required", "safety_health_concern", "training_program_redesign_needed", "regulatory_concern", "cross_property_pattern", "repeat_unresolved", "low_confidence", "manual_review_required", "operator_override" ], "title": "Reason for escalation", "type": "string" }, "escalation_target_staff_id": { "title": "Optional named staff member to route to", "type": "string" } }, "required": [ "escalation_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_recovery_pattern" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.pattern_escalated_to_staff_member" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.service_recovery_pattern", "hospitality.recovery_pattern_detection_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.escalate_via_pattern_assessment:apply" ] } ], "summary": "Escalate via pattern assessment", "tags": [ "recovery_pattern_detection" ] } }, "/v1/actions/hospitality.action.escalate_via_pattern_assessment/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_escalate_via_pattern_assessment` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.escalate_via_pattern_assessment:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_escalate_via_pattern_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "escalation_reason": { "enum": [ "high_severity", "capital_expenditure_required", "safety_health_concern", "training_program_redesign_needed", "regulatory_concern", "cross_property_pattern", "repeat_unresolved", "low_confidence", "manual_review_required", "operator_override" ], "title": "Reason for escalation", "type": "string" }, "escalation_target_staff_id": { "title": "Optional named staff member to route to", "type": "string" } }, "required": [ "escalation_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_recovery_pattern" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.pattern_escalated_to_staff_member" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.service_recovery_pattern", "hospitality.recovery_pattern_detection_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Escalate via pattern assessment (dry-run)", "tags": [ "recovery_pattern_detection" ] } }, "/v1/actions/hospitality.action.escalate_via_pattern_assessment/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_escalate_via_pattern_assessment`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_escalate_via_pattern_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "escalation_reason": { "enum": [ "high_severity", "capital_expenditure_required", "safety_health_concern", "training_program_redesign_needed", "regulatory_concern", "cross_property_pattern", "repeat_unresolved", "low_confidence", "manual_review_required", "operator_override" ], "title": "Reason for escalation", "type": "string" }, "escalation_target_staff_id": { "title": "Optional named staff member to route to", "type": "string" } }, "required": [ "escalation_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_recovery_pattern" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Escalate via pattern assessment (dry-run)", "tags": [ "recovery_pattern_detection" ] } }, "/v1/actions/hospitality.action.escalate_via_pattern_assessment/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_escalate_via_pattern_assessment` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.escalate_via_pattern_assessment:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_escalate_via_pattern_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "escalation_reason": { "enum": [ "high_severity", "capital_expenditure_required", "safety_health_concern", "training_program_redesign_needed", "regulatory_concern", "cross_property_pattern", "repeat_unresolved", "low_confidence", "manual_review_required", "operator_override" ], "title": "Reason for escalation", "type": "string" }, "escalation_target_staff_id": { "title": "Optional named staff member to route to", "type": "string" } }, "required": [ "escalation_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_recovery_pattern" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Escalate via pattern assessment (rollup delta)", "tags": [ "recovery_pattern_detection" ] } }, "/v1/actions/hospitality.action.escalate_via_triage/apply": { "post": { "description": "Escalate a suggested message_triage to staff with a structured handoff payload. Transitions `decision_status` to `escalated`; sets `escalation_reason`; optionally links to a named staff_member. Updates conversation state to `escalated`. The only legal terminal transition for injection.suspected triages.\n\nEffects: modify hospitality.message_triage; modify hospitality.guest_conversation; link hospitality.link.message_triage_escalated_to_staff_member.", "operationId": "apply_hospitality_action_escalate_via_triage", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "escalation_reason": { "enum": [ "low_confidence", "policy_block", "safety_keyword", "explicit_guest_request", "sensitive_topic", "ambiguity", "operator_override", "pci_disclosed", "phi_disclosed" ], "title": "Reason for escalation", "type": "string" }, "escalation_target_staff_id": { "title": "Optional named staff member to route to", "type": "string" } }, "required": [ "escalation_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.message_triage" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.message_triage_escalated_to_staff_member" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.message_triage", "hospitality.guest_conversation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.escalate_via_triage:apply" ] } ], "summary": "Escalate via triage", "tags": [ "messaging" ] } }, "/v1/actions/hospitality.action.escalate_via_triage/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_escalate_via_triage` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.escalate_via_triage:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_escalate_via_triage", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "escalation_reason": { "enum": [ "low_confidence", "policy_block", "safety_keyword", "explicit_guest_request", "sensitive_topic", "ambiguity", "operator_override", "pci_disclosed", "phi_disclosed" ], "title": "Reason for escalation", "type": "string" }, "escalation_target_staff_id": { "title": "Optional named staff member to route to", "type": "string" } }, "required": [ "escalation_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.message_triage" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.message_triage_escalated_to_staff_member" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.message_triage", "hospitality.guest_conversation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Escalate via triage (dry-run)", "tags": [ "messaging" ] } }, "/v1/actions/hospitality.action.escalate_via_triage/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_escalate_via_triage`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_escalate_via_triage", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "escalation_reason": { "enum": [ "low_confidence", "policy_block", "safety_keyword", "explicit_guest_request", "sensitive_topic", "ambiguity", "operator_override", "pci_disclosed", "phi_disclosed" ], "title": "Reason for escalation", "type": "string" }, "escalation_target_staff_id": { "title": "Optional named staff member to route to", "type": "string" } }, "required": [ "escalation_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.message_triage" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Escalate via triage (dry-run)", "tags": [ "messaging" ] } }, "/v1/actions/hospitality.action.escalate_via_triage/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_escalate_via_triage` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.escalate_via_triage:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_escalate_via_triage", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "escalation_reason": { "enum": [ "low_confidence", "policy_block", "safety_keyword", "explicit_guest_request", "sensitive_topic", "ambiguity", "operator_override", "pci_disclosed", "phi_disclosed" ], "title": "Reason for escalation", "type": "string" }, "escalation_target_staff_id": { "title": "Optional named staff member to route to", "type": "string" } }, "required": [ "escalation_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.message_triage" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Escalate via triage (rollup delta)", "tags": [ "messaging" ] } }, "/v1/actions/hospitality.action.execute_management_agreement/apply": { "post": { "description": "Execute an HMA with the target owner company (kind = hotel_owner): creates the `management_agreement` carrying the fee schedule, delegation thresholds and performance-test parameters, linked to the owner. Covered properties join via `add_property_to_management_agreement`. `external_ref` is the idempotency anchor for provisioning replays.\n\nEffects: create hospitality.management_agreement; link hospitality.link.management_agreement_with_company.", "operationId": "apply_hospitality_action_execute_management_agreement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "accounting_fee_monthly": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Centralised-accounting charge per month", "type": "object" }, "base_fee_pct_revenue": { "format": "decimal", "title": "Base fee as a fraction of total operating revenue", "type": "string" }, "budget_aggregate_flex_pct": { "format": "decimal", "title": "Aggregate overspend ceiling", "type": "string" }, "budget_line_flex_pct": { "format": "decimal", "title": "Per-line-item overspend delegation", "type": "string" }, "capex_approval_threshold": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Owner-approval threshold for capital spend", "type": "object" }, "code": { "title": "Agreement code", "type": "string" }, "commenced_on": { "format": "date", "title": "Commencement date", "type": "string" }, "contract_approval_threshold": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Owner-approval threshold for contract value", "type": "object" }, "cure_window_months": { "title": "Cure window after a performance failure (months)", "type": "integer" }, "external_ref": { "title": "Provisioning idempotency anchor", "type": "string" }, "incentive_kind": { "enum": [ "pct_agop_over_priority", "pct_noi_attainment", "none" ], "title": "Incentive-fee structure", "type": "string" }, "incentive_pct": { "format": "decimal", "title": "Incentive fee fraction (per incentive_kind)", "type": "string" }, "initial_term_years": { "title": "Initial term (years)", "type": "integer" }, "name": { "title": "Agreement name", "type": "string" }, "noi_budget_floor_pct": { "format": "decimal", "title": "Performance test: minimum actual/budgeted NOI", "type": "string" }, "owner_priority_return_pct": { "format": "decimal", "title": "Owner-priority hurdle fraction (pct_agop_over_priority only)", "type": "string" }, "radius_miles": { "format": "decimal", "title": "Area-of-protection radius (miles)", "type": "string" }, "revenue_management_fee_monthly": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Centralised revenue-management charge per month", "type": "object" }, "revpar_index_floor_pct": { "format": "decimal", "title": "Performance test: minimum RevPAR index vs prior year", "type": "string" } }, "required": [ "code", "name", "commenced_on", "initial_term_years", "base_fee_pct_revenue", "incentive_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.company" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.management_agreement_with_company" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.management_agreement" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.execute_management_agreement:apply" ] } ], "summary": "Execute management agreement", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.execute_management_agreement/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_execute_management_agreement` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.execute_management_agreement:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_execute_management_agreement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "accounting_fee_monthly": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Centralised-accounting charge per month", "type": "object" }, "base_fee_pct_revenue": { "format": "decimal", "title": "Base fee as a fraction of total operating revenue", "type": "string" }, "budget_aggregate_flex_pct": { "format": "decimal", "title": "Aggregate overspend ceiling", "type": "string" }, "budget_line_flex_pct": { "format": "decimal", "title": "Per-line-item overspend delegation", "type": "string" }, "capex_approval_threshold": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Owner-approval threshold for capital spend", "type": "object" }, "code": { "title": "Agreement code", "type": "string" }, "commenced_on": { "format": "date", "title": "Commencement date", "type": "string" }, "contract_approval_threshold": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Owner-approval threshold for contract value", "type": "object" }, "cure_window_months": { "title": "Cure window after a performance failure (months)", "type": "integer" }, "external_ref": { "title": "Provisioning idempotency anchor", "type": "string" }, "incentive_kind": { "enum": [ "pct_agop_over_priority", "pct_noi_attainment", "none" ], "title": "Incentive-fee structure", "type": "string" }, "incentive_pct": { "format": "decimal", "title": "Incentive fee fraction (per incentive_kind)", "type": "string" }, "initial_term_years": { "title": "Initial term (years)", "type": "integer" }, "name": { "title": "Agreement name", "type": "string" }, "noi_budget_floor_pct": { "format": "decimal", "title": "Performance test: minimum actual/budgeted NOI", "type": "string" }, "owner_priority_return_pct": { "format": "decimal", "title": "Owner-priority hurdle fraction (pct_agop_over_priority only)", "type": "string" }, "radius_miles": { "format": "decimal", "title": "Area-of-protection radius (miles)", "type": "string" }, "revenue_management_fee_monthly": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Centralised revenue-management charge per month", "type": "object" }, "revpar_index_floor_pct": { "format": "decimal", "title": "Performance test: minimum RevPAR index vs prior year", "type": "string" } }, "required": [ "code", "name", "commenced_on", "initial_term_years", "base_fee_pct_revenue", "incentive_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.company" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.management_agreement_with_company" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.management_agreement" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Execute management agreement (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.execute_management_agreement/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_execute_management_agreement`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_execute_management_agreement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "accounting_fee_monthly": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Centralised-accounting charge per month", "type": "object" }, "base_fee_pct_revenue": { "format": "decimal", "title": "Base fee as a fraction of total operating revenue", "type": "string" }, "budget_aggregate_flex_pct": { "format": "decimal", "title": "Aggregate overspend ceiling", "type": "string" }, "budget_line_flex_pct": { "format": "decimal", "title": "Per-line-item overspend delegation", "type": "string" }, "capex_approval_threshold": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Owner-approval threshold for capital spend", "type": "object" }, "code": { "title": "Agreement code", "type": "string" }, "commenced_on": { "format": "date", "title": "Commencement date", "type": "string" }, "contract_approval_threshold": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Owner-approval threshold for contract value", "type": "object" }, "cure_window_months": { "title": "Cure window after a performance failure (months)", "type": "integer" }, "external_ref": { "title": "Provisioning idempotency anchor", "type": "string" }, "incentive_kind": { "enum": [ "pct_agop_over_priority", "pct_noi_attainment", "none" ], "title": "Incentive-fee structure", "type": "string" }, "incentive_pct": { "format": "decimal", "title": "Incentive fee fraction (per incentive_kind)", "type": "string" }, "initial_term_years": { "title": "Initial term (years)", "type": "integer" }, "name": { "title": "Agreement name", "type": "string" }, "noi_budget_floor_pct": { "format": "decimal", "title": "Performance test: minimum actual/budgeted NOI", "type": "string" }, "owner_priority_return_pct": { "format": "decimal", "title": "Owner-priority hurdle fraction (pct_agop_over_priority only)", "type": "string" }, "radius_miles": { "format": "decimal", "title": "Area-of-protection radius (miles)", "type": "string" }, "revenue_management_fee_monthly": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Centralised revenue-management charge per month", "type": "object" }, "revpar_index_floor_pct": { "format": "decimal", "title": "Performance test: minimum RevPAR index vs prior year", "type": "string" } }, "required": [ "code", "name", "commenced_on", "initial_term_years", "base_fee_pct_revenue", "incentive_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.company" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Execute management agreement (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.execute_management_agreement/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_execute_management_agreement` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.execute_management_agreement:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_execute_management_agreement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "accounting_fee_monthly": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Centralised-accounting charge per month", "type": "object" }, "base_fee_pct_revenue": { "format": "decimal", "title": "Base fee as a fraction of total operating revenue", "type": "string" }, "budget_aggregate_flex_pct": { "format": "decimal", "title": "Aggregate overspend ceiling", "type": "string" }, "budget_line_flex_pct": { "format": "decimal", "title": "Per-line-item overspend delegation", "type": "string" }, "capex_approval_threshold": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Owner-approval threshold for capital spend", "type": "object" }, "code": { "title": "Agreement code", "type": "string" }, "commenced_on": { "format": "date", "title": "Commencement date", "type": "string" }, "contract_approval_threshold": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Owner-approval threshold for contract value", "type": "object" }, "cure_window_months": { "title": "Cure window after a performance failure (months)", "type": "integer" }, "external_ref": { "title": "Provisioning idempotency anchor", "type": "string" }, "incentive_kind": { "enum": [ "pct_agop_over_priority", "pct_noi_attainment", "none" ], "title": "Incentive-fee structure", "type": "string" }, "incentive_pct": { "format": "decimal", "title": "Incentive fee fraction (per incentive_kind)", "type": "string" }, "initial_term_years": { "title": "Initial term (years)", "type": "integer" }, "name": { "title": "Agreement name", "type": "string" }, "noi_budget_floor_pct": { "format": "decimal", "title": "Performance test: minimum actual/budgeted NOI", "type": "string" }, "owner_priority_return_pct": { "format": "decimal", "title": "Owner-priority hurdle fraction (pct_agop_over_priority only)", "type": "string" }, "radius_miles": { "format": "decimal", "title": "Area-of-protection radius (miles)", "type": "string" }, "revenue_management_fee_monthly": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Centralised revenue-management charge per month", "type": "object" }, "revpar_index_floor_pct": { "format": "decimal", "title": "Performance test: minimum RevPAR index vs prior year", "type": "string" } }, "required": [ "code", "name", "commenced_on", "initial_term_years", "base_fee_pct_revenue", "incentive_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.company" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Execute management agreement (rollup delta)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.expire_approval_gate/apply": { "post": { "description": "Expire a live (non-terminal) approval gate whose `expires_at` has elapsed: transitions the gate to `expired` and emits `approval_gate.expired`. Rejected while `expires_at` is absent or still in the future. The parked workflow step is untouched — an expired gate blocks execution; re-request or cancel to move on.\n\nEffects: modify hospitality.approval_gate.", "operationId": "apply_hospitality_action_expire_approval_gate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.approval_gate" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.approval_gate" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.expire_approval_gate:apply" ] } ], "summary": "Expire approval gate", "tags": [ "approvals" ] } }, "/v1/actions/hospitality.action.expire_approval_gate/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_expire_approval_gate` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.expire_approval_gate:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_expire_approval_gate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.approval_gate" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.approval_gate" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Expire approval gate (dry-run)", "tags": [ "approvals" ] } }, "/v1/actions/hospitality.action.expire_approval_gate/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_expire_approval_gate`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_expire_approval_gate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.approval_gate" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Expire approval gate (dry-run)", "tags": [ "approvals" ] } }, "/v1/actions/hospitality.action.expire_approval_gate/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_expire_approval_gate` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.expire_approval_gate:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_expire_approval_gate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.approval_gate" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Expire approval gate (rollup delta)", "tags": [ "approvals" ] } }, "/v1/actions/hospitality.action.expire_federated_run/apply": { "post": { "description": "Past-deadline expiry of a federated run. Settlement logic is identical to `cancel_federated_run` (release the reservation unless local DP spend has already occurred), with the additional precondition that `deadline_at` on the run has passed. Intended for periodic operator sweeps that recover budget from runs that never made it to aggregation. Refuses if the deadline has not yet passed.\n\nEffects: modify hospitality.federated_run; create hospitality.privacy_budget_event; modify hospitality.privacy_budget_account.", "operationId": "apply_hospitality_action_expire_federated_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.federated_run", "hospitality.privacy_budget_event", "hospitality.privacy_budget_account" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.expire_federated_run:apply" ] } ], "summary": "Expire federated run", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.expire_federated_run/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_expire_federated_run` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.expire_federated_run:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_expire_federated_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.federated_run", "hospitality.privacy_budget_event", "hospitality.privacy_budget_account" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Expire federated run (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.expire_federated_run/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_expire_federated_run`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_expire_federated_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Expire federated run (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.expire_federated_run/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_expire_federated_run` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.expire_federated_run:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_expire_federated_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Expire federated run (rollup delta)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.expire_fraud_assessments/apply": { "post": { "description": "Sweep assessments on the target property whose `expires_at` is at or before `swept_at` (default now) and whose `decision_status` is still `suggested`, transitioning them to `expired`. Idempotent: re-run after an empty sweep is a no-op. Each transition emits a single event.\n\nEffects: modify hospitality.fraud_risk_assessment.", "operationId": "apply_hospitality_action_expire_fraud_assessments", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "swept_at": { "format": "date-time", "title": "The instant the sweep judges expiry against and stamps as `decided_at` (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.fraud_risk_assessment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.expire_fraud_assessments:apply" ] } ], "summary": "Expire fraud assessments", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.expire_fraud_assessments/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_expire_fraud_assessments` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.expire_fraud_assessments:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_expire_fraud_assessments", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "swept_at": { "format": "date-time", "title": "The instant the sweep judges expiry against and stamps as `decided_at` (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.fraud_risk_assessment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Expire fraud assessments (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.expire_fraud_assessments/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_expire_fraud_assessments`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_expire_fraud_assessments", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "swept_at": { "format": "date-time", "title": "The instant the sweep judges expiry against and stamps as `decided_at` (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Expire fraud assessments (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.expire_fraud_assessments/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_expire_fraud_assessments` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.expire_fraud_assessments:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_expire_fraud_assessments", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "swept_at": { "format": "date-time", "title": "The instant the sweep judges expiry against and stamps as `decided_at` (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Expire fraud assessments (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.expire_message_triages/apply": { "post": { "description": "Sweep triages on the target property whose `expires_at` is at or before `swept_at` (default now) and whose `decision_status` is still `suggested`, transitioning them to `expired`. Idempotent: re-run after an empty sweep is a no-op. Each transition emits a single event.\n\nEffects: modify hospitality.message_triage; modify hospitality.guest_conversation.", "operationId": "apply_hospitality_action_expire_message_triages", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "swept_at": { "format": "date-time", "title": "The instant the sweep judges expiry against and stamps as `decided_at` (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.message_triage", "hospitality.guest_conversation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.expire_message_triages:apply" ] } ], "summary": "Expire message triages", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.expire_message_triages/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_expire_message_triages` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.expire_message_triages:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_expire_message_triages", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "swept_at": { "format": "date-time", "title": "The instant the sweep judges expiry against and stamps as `decided_at` (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.message_triage", "hospitality.guest_conversation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Expire message triages (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.expire_message_triages/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_expire_message_triages`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_expire_message_triages", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "swept_at": { "format": "date-time", "title": "The instant the sweep judges expiry against and stamps as `decided_at` (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Expire message triages (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.expire_message_triages/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_expire_message_triages` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.expire_message_triages:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_expire_message_triages", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "swept_at": { "format": "date-time", "title": "The instant the sweep judges expiry against and stamps as `decided_at` (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Expire message triages (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.expire_pattern_assessments/apply": { "post": { "description": "Sweep suggested service_recovery_pattern rows on the target property whose expires_at is in the past.\n\nEffects: modify hospitality.service_recovery_pattern; modify hospitality.recovery_pattern_detection_run.", "operationId": "apply_hospitality_action_expire_pattern_assessments", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.service_recovery_pattern", "hospitality.recovery_pattern_detection_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.expire_pattern_assessments:apply" ] } ], "summary": "Expire pattern assessments", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.expire_pattern_assessments/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_expire_pattern_assessments` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.expire_pattern_assessments:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_expire_pattern_assessments", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.service_recovery_pattern", "hospitality.recovery_pattern_detection_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Expire pattern assessments (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.expire_pattern_assessments/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_expire_pattern_assessments`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_expire_pattern_assessments", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Expire pattern assessments (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.expire_pattern_assessments/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_expire_pattern_assessments` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.expire_pattern_assessments:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_expire_pattern_assessments", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Expire pattern assessments (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.expire_proposed_actions/apply": { "post": { "description": "Batch sweep moving `proposed` rows past their `expires_at` to `expired`, run from the pruner cadence alongside `expire_message_triages` / `expire_fraud_assessments`. Emits `proposed_action.expired` when any row was swept.\n\nEffects: modify hospitality.proposed_action.", "operationId": "apply_hospitality_action_expire_proposed_actions", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.proposed_action" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.expire_proposed_actions:apply" ] } ], "summary": "Expire proposed actions", "tags": [ "proposed_action" ] } }, "/v1/actions/hospitality.action.expire_proposed_actions/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_expire_proposed_actions` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.expire_proposed_actions:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_expire_proposed_actions", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.proposed_action" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Expire proposed actions (dry-run)", "tags": [ "proposed_action" ] } }, "/v1/actions/hospitality.action.expire_proposed_actions/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_expire_proposed_actions`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_expire_proposed_actions", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Expire proposed actions (dry-run)", "tags": [ "proposed_action" ] } }, "/v1/actions/hospitality.action.expire_proposed_actions/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_expire_proposed_actions` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.expire_proposed_actions:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_expire_proposed_actions", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Expire proposed actions (rollup delta)", "tags": [ "proposed_action" ] } }, "/v1/actions/hospitality.action.expire_purpose_grant/apply": { "post": { "description": "Transition an overdue `requested`/`active` grant to `expired` — invoked by the §9.1 expiry sweep when `expires_at` elapses (the grant implements the `expirable` interface); also callable by an operator forcing the question. Idempotent on a terminal grant. Emits `purpose_grant.expired`.\n\nEffects: modify hospitality.purpose_grant.", "operationId": "apply_hospitality_action_expire_purpose_grant", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.purpose_grant" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.purpose_grant" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.expire_purpose_grant:apply" ] } ], "summary": "Expire purpose grant", "tags": [ "pbac" ] } }, "/v1/actions/hospitality.action.expire_purpose_grant/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_expire_purpose_grant` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.expire_purpose_grant:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_expire_purpose_grant", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.purpose_grant" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.purpose_grant" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Expire purpose grant (dry-run)", "tags": [ "pbac" ] } }, "/v1/actions/hospitality.action.expire_purpose_grant/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_expire_purpose_grant`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_expire_purpose_grant", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.purpose_grant" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Expire purpose grant (dry-run)", "tags": [ "pbac" ] } }, "/v1/actions/hospitality.action.expire_purpose_grant/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_expire_purpose_grant` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.expire_purpose_grant:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_expire_purpose_grant", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.purpose_grant" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Expire purpose grant (rollup delta)", "tags": [ "pbac" ] } }, "/v1/actions/hospitality.action.expire_rate_recommendations/apply": { "post": { "description": "Sweep recommendations on the target property whose `expires_at` is in the past (or whose `expires_on` business day the house has closed) and whose `decision_status` is still `suggested`, transitioning them to `expired`. Idempotent: a re-run after an empty sweep is a no-op. Each transition emits a single event so the audit trail captures the sweep.\n\nEffects: modify hospitality.rate_recommendation; modify hospitality.rate_recommendation_run.", "operationId": "apply_hospitality_action_expire_rate_recommendations", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.rate_recommendation", "hospitality.rate_recommendation_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.expire_rate_recommendations:apply" ] } ], "summary": "Expire rate recommendations", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.expire_rate_recommendations/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_expire_rate_recommendations` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.expire_rate_recommendations:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_expire_rate_recommendations", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.rate_recommendation", "hospitality.rate_recommendation_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Expire rate recommendations (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.expire_rate_recommendations/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_expire_rate_recommendations`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_expire_rate_recommendations", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Expire rate recommendations (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.expire_rate_recommendations/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_expire_rate_recommendations` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.expire_rate_recommendations:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_expire_rate_recommendations", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Expire rate recommendations (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.expire_restriction_recommendations/apply": { "post": { "description": "Sweep restriction recommendations on the target property whose `expires_at` is in the past (or whose `expires_on` business day the house has closed) and whose `decision_status` is still `suggested`, transitioning them to `expired`. Idempotent: a re-run after an empty sweep is a no-op. The sibling of `expire_rate_recommendations`, one sweep per recommendation kind.\n\nEffects: modify hospitality.restriction_recommendation; modify hospitality.rate_recommendation_run.", "operationId": "apply_hospitality_action_expire_restriction_recommendations", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.restriction_recommendation", "hospitality.rate_recommendation_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.expire_restriction_recommendations:apply" ] } ], "summary": "Expire restriction recommendations", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.expire_restriction_recommendations/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_expire_restriction_recommendations` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.expire_restriction_recommendations:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_expire_restriction_recommendations", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.restriction_recommendation", "hospitality.rate_recommendation_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Expire restriction recommendations (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.expire_restriction_recommendations/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_expire_restriction_recommendations`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_expire_restriction_recommendations", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Expire restriction recommendations (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.expire_restriction_recommendations/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_expire_restriction_recommendations` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.expire_restriction_recommendations:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_expire_restriction_recommendations", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Expire restriction recommendations (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.expire_retained_record/apply": { "post": { "description": "Retire a record whose storage-limitation clock has run out: once `retain_until` is in the past, every property carrying a marking is cleared and the record is soft-deleted, so it is neither held in readable form nor returned by any read. Invoked by the retention sweep (`aerandil-api::retention_sweep`) for each `retention_bound` record past its date; an operator may call it too, but it refuses a record whose date has not passed — early erasure is the erasure-request path, not this one. The record's events carry no values (each implementer is `event_image_suppressed`), so nothing marked survives in the log.\n\nEffects: modify hospitality.booking_origin; delete hospitality.booking_origin; modify hospitality.payment_card; delete hospitality.payment_card; modify hospitality.guest_id_document; delete hospitality.guest_id_document.", "operationId": "apply_hospitality_action_expire_retained_record", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "deleted" ] }, "object_type": { "enum": [ "hospitality.booking_origin", "hospitality.payment_card", "hospitality.guest_id_document" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.expire_retained_record:apply" ] } ], "summary": "Expire retained record", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.expire_retained_record/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_expire_retained_record` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.expire_retained_record:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_expire_retained_record", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "deleted" ] }, "object_type": { "enum": [ "hospitality.booking_origin", "hospitality.payment_card", "hospitality.guest_id_document" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Expire retained record (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.expire_retained_record/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_expire_retained_record`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_expire_retained_record", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Expire retained record (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.expire_retained_record/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_expire_retained_record` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.expire_retained_record:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_expire_retained_record", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Expire retained record (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.expire_sell_limit_recommendations/apply": { "post": { "description": "Sweep sell-limit recommendations on the target property whose `expires_at` is in the past (or whose `expires_on` business day the house has closed) and whose `decision_status` is still `suggested`, transitioning them to `expired`. Idempotent: a re-run after an empty sweep is a no-op. One sweep per recommendation kind, beside `expire_rate_recommendations` and `expire_restriction_recommendations`.\n\nEffects: modify hospitality.sell_limit_recommendation; modify hospitality.rate_recommendation_run.", "operationId": "apply_hospitality_action_expire_sell_limit_recommendations", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.sell_limit_recommendation", "hospitality.rate_recommendation_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.expire_sell_limit_recommendations:apply" ] } ], "summary": "Expire sell-limit recommendations", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.expire_sell_limit_recommendations/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_expire_sell_limit_recommendations` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.expire_sell_limit_recommendations:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_expire_sell_limit_recommendations", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.sell_limit_recommendation", "hospitality.rate_recommendation_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Expire sell-limit recommendations (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.expire_sell_limit_recommendations/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_expire_sell_limit_recommendations`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_expire_sell_limit_recommendations", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Expire sell-limit recommendations (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.expire_sell_limit_recommendations/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_expire_sell_limit_recommendations` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.expire_sell_limit_recommendations:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_expire_sell_limit_recommendations", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Expire sell-limit recommendations (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.expire_workflow_run/apply": { "post": { "description": "Expire a non-terminal workflow run whose `expires_at` has elapsed. Pending steps (planned / ready / waiting_*) transition to `expired` with `workflow_step.expired` events; the run transitions to `expired` and emits `workflow_run.expired`. Rejected while `expires_at` is absent or still in the future. No compensation is attempted — an operator who wants compensation cancels with `compensate_completed_steps = true` before expiry.\n\nEffects: modify hospitality.workflow_run; modify hospitality.workflow_step_run.", "operationId": "apply_hospitality_action_expire_workflow_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.workflow_run", "hospitality.workflow_step_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.expire_workflow_run:apply" ] } ], "summary": "Expire workflow run", "tags": [ "workflows" ] } }, "/v1/actions/hospitality.action.expire_workflow_run/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_expire_workflow_run` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.expire_workflow_run:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_expire_workflow_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.workflow_run", "hospitality.workflow_step_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Expire workflow run (dry-run)", "tags": [ "workflows" ] } }, "/v1/actions/hospitality.action.expire_workflow_run/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_expire_workflow_run`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_expire_workflow_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Expire workflow run (dry-run)", "tags": [ "workflows" ] } }, "/v1/actions/hospitality.action.expire_workflow_run/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_expire_workflow_run` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.expire_workflow_run:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_expire_workflow_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Expire workflow run (rollup delta)", "tags": [ "workflows" ] } }, "/v1/actions/hospitality.action.fire_course/apply": { "post": { "description": "Send one course's entered lines to the kitchen — the service-total moment of a round (Simphony). Lines move to `fired`, and one kitchen ticket is cut per prep station represented in the course (Toast coursing model); lines whose item has no station binding land on an unrouted (expo) ticket. A modifier line fires with its parent, on its parent's ticket. Firing an already-fired course again picks up only newly-entered lines. Emits `fnb.course_fired`.\n\nEffects: modify hospitality.check_line; create hospitality.kitchen_ticket; link hospitality.link.ticket_for_check; link hospitality.link.ticket_at_station; link hospitality.link.check_line_on_ticket.", "operationId": "apply_hospitality_action_fire_course", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "course_number": { "title": "Course to fire", "type": "integer" }, "fired_at": { "format": "date-time", "title": "When the course fired — business time for replayed histories (defaults to now)", "type": "string" } }, "required": [ "course_number" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.ticket_for_check", "hospitality.link.ticket_at_station", "hospitality.link.check_line_on_ticket" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.check_line", "hospitality.kitchen_ticket" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.fire_course:apply" ] } ], "summary": "Fire course", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.fire_course/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_fire_course` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.fire_course:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_fire_course", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "course_number": { "title": "Course to fire", "type": "integer" }, "fired_at": { "format": "date-time", "title": "When the course fired — business time for replayed histories (defaults to now)", "type": "string" } }, "required": [ "course_number" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.ticket_for_check", "hospitality.link.ticket_at_station", "hospitality.link.check_line_on_ticket" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.check_line", "hospitality.kitchen_ticket" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Fire course (dry-run)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.fire_course/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_fire_course`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_fire_course", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "course_number": { "title": "Course to fire", "type": "integer" }, "fired_at": { "format": "date-time", "title": "When the course fired — business time for replayed histories (defaults to now)", "type": "string" } }, "required": [ "course_number" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Fire course (dry-run)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.fire_course/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_fire_course` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.fire_course:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_fire_course", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "course_number": { "title": "Course to fire", "type": "integer" }, "fired_at": { "format": "date-time", "title": "When the course fired — business time for replayed histories (defaults to now)", "type": "string" } }, "required": [ "course_number" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Fire course (rollup delta)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.forfeit_deposit/apply": { "post": { "description": "Post a forfeited-deposit charge against the reservation's folio — the stay's when there is one, the booking's own account otherwise, opened here so a cancelled booking's charge is one a bill can show. The deposit already taken moves onto that folio as the credit the charge consumes, up to the amount forfeited. Posts under USALI `miscellaneous_income` with `system_charge_kind = forfeited_deposit`. Idempotent on (reservation, business_date, forfeiture_amount). Tax is derived from the rules the house authored for a `forfeited_deposit` active on the business date — a UK house taxes it as consideration for the room that was booked, an Austrian one does not — and a house with no such rule posts the charge untaxed. A booking's tax exemption reaches it. Refused once a cancellation fee is posted on the booking (`post_cancellation_fee`, 2026-10-27): the deposit on its account already pays toward that fee, and Keep and Charge are one decision.\n\nEffects: create hospitality.charge; modify hospitality.reservation; link hospitality.link.folio_has_charge; link hospitality.link.charge_at_outlet; create hospitality.folio; link hospitality.link.reservation_has_folio; create hospitality.payment; link hospitality.link.folio_has_payment; modify hospitality.folio; create hospitality.tax_application; link hospitality.link.charge_has_tax_application.", "operationId": "apply_hospitality_action_forfeit_deposit", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" }, "forfeiture_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Forfeiture amount", "type": "object" }, "outlet_id": { "format": "uuid", "title": "USALI 12 outlet the forfeiture rolls up to — typically the property's `miscellaneous_income` outlet (proposal 0023)", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "reason_code": { "title": "Reason code", "type": "string" } }, "required": [ "forfeiture_amount", "business_date", "outlet_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_charge", "hospitality.link.charge_at_outlet", "hospitality.link.reservation_has_folio", "hospitality.link.folio_has_payment", "hospitality.link.charge_has_tax_application" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.charge", "hospitality.reservation", "hospitality.folio", "hospitality.payment", "hospitality.tax_application" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.forfeit_deposit:apply" ] } ], "summary": "Forfeit deposit", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.forfeit_deposit/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_forfeit_deposit` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.forfeit_deposit:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_forfeit_deposit", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" }, "forfeiture_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Forfeiture amount", "type": "object" }, "outlet_id": { "format": "uuid", "title": "USALI 12 outlet the forfeiture rolls up to — typically the property's `miscellaneous_income` outlet (proposal 0023)", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "reason_code": { "title": "Reason code", "type": "string" } }, "required": [ "forfeiture_amount", "business_date", "outlet_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_charge", "hospitality.link.charge_at_outlet", "hospitality.link.reservation_has_folio", "hospitality.link.folio_has_payment", "hospitality.link.charge_has_tax_application" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.charge", "hospitality.reservation", "hospitality.folio", "hospitality.payment", "hospitality.tax_application" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Forfeit deposit (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.forfeit_deposit/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_forfeit_deposit`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_forfeit_deposit", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" }, "forfeiture_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Forfeiture amount", "type": "object" }, "outlet_id": { "format": "uuid", "title": "USALI 12 outlet the forfeiture rolls up to — typically the property's `miscellaneous_income` outlet (proposal 0023)", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "reason_code": { "title": "Reason code", "type": "string" } }, "required": [ "forfeiture_amount", "business_date", "outlet_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Forfeit deposit (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.forfeit_deposit/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_forfeit_deposit` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.forfeit_deposit:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_forfeit_deposit", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" }, "forfeiture_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Forfeiture amount", "type": "object" }, "outlet_id": { "format": "uuid", "title": "USALI 12 outlet the forfeiture rolls up to — typically the property's `miscellaneous_income` outlet (proposal 0023)", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "reason_code": { "title": "Reason code", "type": "string" } }, "required": [ "forfeiture_amount", "business_date", "outlet_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Forfeit deposit (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.freeze_membership/apply": { "post": { "description": "Pause the membership. Sets `access_status = frozen` on the membership; when the operator's freeze includes a billing pause, also sets the subscription's `suspension_state` (with `suspension_started_at`).\n\nEffects: modify hospitality.membership; modify hospitality.membership_subscription.", "operationId": "apply_hospitality_action_freeze_membership", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "freeze_reason": { "enum": [ "medically_suspended", "operator_paused", "self_paused" ], "title": "Freeze reason (medically_suspended / operator_paused / self_paused)", "type": "string" }, "frozen_at": { "format": "date-time", "title": "When the freeze took effect", "type": "string" }, "pause_billing": { "title": "Pause subscription billing (the most common case)", "type": "boolean" } }, "required": [ "freeze_reason", "pause_billing", "frozen_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.membership", "hospitality.membership_subscription" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.freeze_membership:apply" ] } ], "summary": "Freeze membership", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.freeze_membership/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_freeze_membership` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.freeze_membership:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_freeze_membership", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "freeze_reason": { "enum": [ "medically_suspended", "operator_paused", "self_paused" ], "title": "Freeze reason (medically_suspended / operator_paused / self_paused)", "type": "string" }, "frozen_at": { "format": "date-time", "title": "When the freeze took effect", "type": "string" }, "pause_billing": { "title": "Pause subscription billing (the most common case)", "type": "boolean" } }, "required": [ "freeze_reason", "pause_billing", "frozen_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.membership", "hospitality.membership_subscription" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Freeze membership (dry-run)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.freeze_membership/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_freeze_membership`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_freeze_membership", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "freeze_reason": { "enum": [ "medically_suspended", "operator_paused", "self_paused" ], "title": "Freeze reason (medically_suspended / operator_paused / self_paused)", "type": "string" }, "frozen_at": { "format": "date-time", "title": "When the freeze took effect", "type": "string" }, "pause_billing": { "title": "Pause subscription billing (the most common case)", "type": "boolean" } }, "required": [ "freeze_reason", "pause_billing", "frozen_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Freeze membership (dry-run)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.freeze_membership/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_freeze_membership` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.freeze_membership:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_freeze_membership", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "freeze_reason": { "enum": [ "medically_suspended", "operator_paused", "self_paused" ], "title": "Freeze reason (medically_suspended / operator_paused / self_paused)", "type": "string" }, "frozen_at": { "format": "date-time", "title": "When the freeze took effect", "type": "string" }, "pause_billing": { "title": "Pause subscription billing (the most common case)", "type": "boolean" } }, "required": [ "freeze_reason", "pause_billing", "frozen_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Freeze membership (rollup delta)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.generate_housekeeping_tasks/apply": { "post": { "description": "Derive the day's housekeeping board from system truth: each occupied room due out on the business date gets a departure clean, other occupied rooms get stayover cleans (and turndown when include_turndown is set), vacant dirty / pickup rooms get vacant pickups, and rooms under an active out-of-order block covering the date are skipped (release decides their state). Rooms whose reservation is waiting in the room queue generate at urgent priority. Idempotent by construction: every derived task carries a generation_key, so re-running lands on the existing rows, and generated pending / blocked tasks the current state no longer calls for retire as skipped. Manually minted tasks are never touched. Each new task carries `credits` and `standard_minutes` from the property's most specific active housekeeping credit rule (task type and room type over task type alone; none when the house prices none), and a re-run re-prices generated tasks still pending to the rules as they stand — work under way keeps its price. Every active public area of the house gets one `public_area_clean` for the date (2026-10-14), keyed `hk:area:{area}:{date}` and converging the same way: a retired area's open generated clean is skipped, an active one's skipped clean revives. Run it from a cron, an agent, or the desk — twice is safe.\n\nEffects: create hospitality.housekeeping_task; modify hospitality.housekeeping_task; link hospitality.link.housekeeping_task_for_room; link hospitality.link.housekeeping_task_for_area.", "operationId": "apply_hospitality_action_generate_housekeeping_tasks", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Service date to generate for", "type": "string" }, "include_turndown": { "title": "Also generate evening turndown tasks for stayover rooms", "type": "boolean" } }, "required": [ "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.housekeeping_task_for_room", "hospitality.link.housekeeping_task_for_area" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.generate_housekeeping_tasks:apply" ] } ], "summary": "Generate housekeeping tasks", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.generate_housekeeping_tasks/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_generate_housekeeping_tasks` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.generate_housekeeping_tasks:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_generate_housekeeping_tasks", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Service date to generate for", "type": "string" }, "include_turndown": { "title": "Also generate evening turndown tasks for stayover rooms", "type": "boolean" } }, "required": [ "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.housekeeping_task_for_room", "hospitality.link.housekeeping_task_for_area" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Generate housekeeping tasks (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.generate_housekeeping_tasks/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_generate_housekeeping_tasks`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_generate_housekeeping_tasks", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Service date to generate for", "type": "string" }, "include_turndown": { "title": "Also generate evening turndown tasks for stayover rooms", "type": "boolean" } }, "required": [ "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Generate housekeeping tasks (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.generate_housekeeping_tasks/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_generate_housekeeping_tasks` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.generate_housekeeping_tasks:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_generate_housekeeping_tasks", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Service date to generate for", "type": "string" }, "include_turndown": { "title": "Also generate evening turndown tasks for stayover rooms", "type": "boolean" } }, "required": [ "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Generate housekeeping tasks (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.grant_consent/apply": { "post": { "description": "Write the next monotonic version of the tenant's `consent_policy`. The first grant creates the policy at version 1; each subsequent grant supersedes it with a strictly greater version (the prior version stays in the object's event history). `default_scope` is the deny-by-omission `ConsentScope` applied to objects that carry none; `purposes_grantable` bounds what any scope under this policy may grant. Emits `consent.policy_granted`.\n\nEffects: create hospitality.consent_policy; modify hospitality.consent_policy.", "operationId": "apply_hospitality_action_grant_consent", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "default_scope": { "additionalProperties": true, "title": "Default ConsentScope applied to objects without their own scope", "type": "object" }, "effective_from": { "format": "date-time", "title": "When this policy version takes effect", "type": "string" }, "effective_until": { "format": "date-time", "title": "When this policy version is superseded", "type": "string" }, "min_cohort_size": { "title": "Kernel-level k-anonymity floor (default 5)", "type": "integer" }, "policy_text_uri": { "title": "Opaque pointer to the human-readable policy document", "type": "string" }, "purposes_grantable": { "items": { "enum": [ "operational", "benchmark_aggregate", "federated_query", "federated_training", "model_distillation", "fraud_network" ], "type": "string" }, "title": "Purposes this policy may grant", "type": "array" }, "regulatory_basis": { "title": "Regulatory regime this policy is written under (GDPR / CCPA / UK DUA …)", "type": "string" }, "verified_by": { "title": "Principal::stable_id() of the DPO sign-off, when verified", "type": "string" } }, "required": [ "default_scope", "purposes_grantable", "effective_from", "regulatory_basis" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.consent_policy" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.grant_consent:apply" ] } ], "summary": "Grant consent", "tags": [ "consent" ] } }, "/v1/actions/hospitality.action.grant_consent/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_grant_consent` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.grant_consent:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_grant_consent", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "default_scope": { "additionalProperties": true, "title": "Default ConsentScope applied to objects without their own scope", "type": "object" }, "effective_from": { "format": "date-time", "title": "When this policy version takes effect", "type": "string" }, "effective_until": { "format": "date-time", "title": "When this policy version is superseded", "type": "string" }, "min_cohort_size": { "title": "Kernel-level k-anonymity floor (default 5)", "type": "integer" }, "policy_text_uri": { "title": "Opaque pointer to the human-readable policy document", "type": "string" }, "purposes_grantable": { "items": { "enum": [ "operational", "benchmark_aggregate", "federated_query", "federated_training", "model_distillation", "fraud_network" ], "type": "string" }, "title": "Purposes this policy may grant", "type": "array" }, "regulatory_basis": { "title": "Regulatory regime this policy is written under (GDPR / CCPA / UK DUA …)", "type": "string" }, "verified_by": { "title": "Principal::stable_id() of the DPO sign-off, when verified", "type": "string" } }, "required": [ "default_scope", "purposes_grantable", "effective_from", "regulatory_basis" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.consent_policy" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Grant consent (dry-run)", "tags": [ "consent" ] } }, "/v1/actions/hospitality.action.grant_consent/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_grant_consent`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_grant_consent", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "default_scope": { "additionalProperties": true, "title": "Default ConsentScope applied to objects without their own scope", "type": "object" }, "effective_from": { "format": "date-time", "title": "When this policy version takes effect", "type": "string" }, "effective_until": { "format": "date-time", "title": "When this policy version is superseded", "type": "string" }, "min_cohort_size": { "title": "Kernel-level k-anonymity floor (default 5)", "type": "integer" }, "policy_text_uri": { "title": "Opaque pointer to the human-readable policy document", "type": "string" }, "purposes_grantable": { "items": { "enum": [ "operational", "benchmark_aggregate", "federated_query", "federated_training", "model_distillation", "fraud_network" ], "type": "string" }, "title": "Purposes this policy may grant", "type": "array" }, "regulatory_basis": { "title": "Regulatory regime this policy is written under (GDPR / CCPA / UK DUA …)", "type": "string" }, "verified_by": { "title": "Principal::stable_id() of the DPO sign-off, when verified", "type": "string" } }, "required": [ "default_scope", "purposes_grantable", "effective_from", "regulatory_basis" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Grant consent (dry-run)", "tags": [ "consent" ] } }, "/v1/actions/hospitality.action.grant_consent/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_grant_consent` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.grant_consent:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_grant_consent", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "default_scope": { "additionalProperties": true, "title": "Default ConsentScope applied to objects without their own scope", "type": "object" }, "effective_from": { "format": "date-time", "title": "When this policy version takes effect", "type": "string" }, "effective_until": { "format": "date-time", "title": "When this policy version is superseded", "type": "string" }, "min_cohort_size": { "title": "Kernel-level k-anonymity floor (default 5)", "type": "integer" }, "policy_text_uri": { "title": "Opaque pointer to the human-readable policy document", "type": "string" }, "purposes_grantable": { "items": { "enum": [ "operational", "benchmark_aggregate", "federated_query", "federated_training", "model_distillation", "fraud_network" ], "type": "string" }, "title": "Purposes this policy may grant", "type": "array" }, "regulatory_basis": { "title": "Regulatory regime this policy is written under (GDPR / CCPA / UK DUA …)", "type": "string" }, "verified_by": { "title": "Principal::stable_id() of the DPO sign-off, when verified", "type": "string" } }, "required": [ "default_scope", "purposes_grantable", "effective_from", "regulatory_basis" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Grant consent (rollup delta)", "tags": [ "consent" ] } }, "/v1/actions/hospitality.action.hold_commission/apply": { "post": { "description": "Park a commission row so a payment run passes it over — a disputed stay, an agent under review, a figure someone wants to check. Holding is reversible and records why.\n\nEffects: modify hospitality.commission_detail.", "operationId": "apply_hospitality_action_hold_commission", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the row is being held", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.commission_detail" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.commission_detail" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.hold_commission:apply" ] } ], "summary": "Hold commission", "tags": [ "commission" ] } }, "/v1/actions/hospitality.action.hold_commission/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_hold_commission` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.hold_commission:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_hold_commission", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the row is being held", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.commission_detail" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.commission_detail" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Hold commission (dry-run)", "tags": [ "commission" ] } }, "/v1/actions/hospitality.action.hold_commission/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_hold_commission`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_hold_commission", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the row is being held", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.commission_detail" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Hold commission (dry-run)", "tags": [ "commission" ] } }, "/v1/actions/hospitality.action.hold_commission/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_hold_commission` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.hold_commission:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_hold_commission", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the row is being held", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.commission_detail" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Hold commission (rollup delta)", "tags": [ "commission" ] } }, "/v1/actions/hospitality.action.issue_access_credential/apply": { "post": { "description": "Bind a physical credential (room key card, wristband) to an in-house stay by its opaque vendor token — the enrollment tap: after cutting the key, staff tap it on any reader and the UID lands here, no lock-vendor integration required. At most one active credential may hold a token (database invariant); if the same card's previous binding is stale (its stay checked out or the credential expired) it is auto-revoked and the token re-issued, otherwise the issue is refused. Caps bound what the credential can post. Emits `access.credential_issued.recorded`.\n\nEffects: create hospitality.access_credential; modify hospitality.access_credential; link hospitality.link.access_credential_for_stay.", "operationId": "apply_hospitality_action_issue_access_credential", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "daily_cap": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Maximum total per property-local business day", "type": "object" }, "expires_at": { "format": "date-time", "title": "Hard expiry — resolution fails closed past this instant", "type": "string" }, "kind": { "enum": [ "key_card", "wristband", "mobile_key", "other" ], "title": "Credential form", "type": "string" }, "per_charge_cap": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Maximum amount a single tap may post", "type": "object" }, "token": { "title": "Opaque vendor token (the card UID as the reader reports it)", "type": "string" } }, "required": [ "token", "kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.access_credential_for_stay" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.access_credential" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.issue_access_credential:apply" ] } ], "summary": "Issue access credential", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.issue_access_credential/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_issue_access_credential` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.issue_access_credential:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_issue_access_credential", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "daily_cap": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Maximum total per property-local business day", "type": "object" }, "expires_at": { "format": "date-time", "title": "Hard expiry — resolution fails closed past this instant", "type": "string" }, "kind": { "enum": [ "key_card", "wristband", "mobile_key", "other" ], "title": "Credential form", "type": "string" }, "per_charge_cap": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Maximum amount a single tap may post", "type": "object" }, "token": { "title": "Opaque vendor token (the card UID as the reader reports it)", "type": "string" } }, "required": [ "token", "kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.access_credential_for_stay" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.access_credential" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Issue access credential (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.issue_access_credential/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_issue_access_credential`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_issue_access_credential", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "daily_cap": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Maximum total per property-local business day", "type": "object" }, "expires_at": { "format": "date-time", "title": "Hard expiry — resolution fails closed past this instant", "type": "string" }, "kind": { "enum": [ "key_card", "wristband", "mobile_key", "other" ], "title": "Credential form", "type": "string" }, "per_charge_cap": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Maximum amount a single tap may post", "type": "object" }, "token": { "title": "Opaque vendor token (the card UID as the reader reports it)", "type": "string" } }, "required": [ "token", "kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Issue access credential (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.issue_access_credential/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_issue_access_credential` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.issue_access_credential:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_issue_access_credential", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "daily_cap": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Maximum total per property-local business day", "type": "object" }, "expires_at": { "format": "date-time", "title": "Hard expiry — resolution fails closed past this instant", "type": "string" }, "kind": { "enum": [ "key_card", "wristband", "mobile_key", "other" ], "title": "Credential form", "type": "string" }, "per_charge_cap": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Maximum amount a single tap may post", "type": "object" }, "token": { "title": "Opaque vendor token (the card UID as the reader reports it)", "type": "string" } }, "required": [ "token", "kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Issue access credential (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.issue_banquet_event_order/apply": { "post": { "description": "Send the order to the departments: `draft` or `revised` becomes `issued`, the revision number steps, `issued_at` is stamped. Needs at least one line and a `definite` or `actual` event — a tentative function is not cooked for.\n\nEffects: modify hospitality.banquet_event_order.", "operationId": "apply_hospitality_action_issue_banquet_event_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_event_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.banquet_event_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.issue_banquet_event_order:apply" ] } ], "summary": "Issue banquet event order", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.issue_banquet_event_order/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_issue_banquet_event_order` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.issue_banquet_event_order:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_issue_banquet_event_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_event_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.banquet_event_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Issue banquet event order (dry-run)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.issue_banquet_event_order/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_issue_banquet_event_order`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_issue_banquet_event_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_event_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Issue banquet event order (dry-run)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.issue_banquet_event_order/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_issue_banquet_event_order` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.issue_banquet_event_order:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_issue_banquet_event_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_event_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Issue banquet event order (rollup delta)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.issue_invoice/apply": { "post": { "description": "Turn a sealed folio into the numbered document its recipient keeps — a tax invoice, or a credit note when the target is a rebate folio whose original was invoiced. Allocates the next value from the property's series inside this transaction (dense: a failed issue releases the number rather than burning it), snapshots the issuer and the recipient onto the document so a later profile edit cannot rewrite it, copies every charge as a printed line, and derives the per-rate tax bands from the charges' own `tax_application` rows. Accepts two folio states. A `closed` folio at zero balance is the settled stay: nothing is due. An `open` folio already transferred to a company's A/R account (`settle_folio_to_ar` marks and links it but moves no money) is the billed stay: the balance becomes `amount_due`, the folio's `due_at` becomes `due_on`, and issuing SEALS the folio as it goes — which is the only place this verb writes folio state, and why a company's document can be issued at all. Refuses an open folio with no A/R transfer, a void or house folio, a folio whose uncredited invoice already exists, a folio with no charges, a property with no `billing_identity`, a recipient that cannot be resolved, and — above the property's simplified-invoice threshold — a recipient without a name, city, postcode and country. Below that threshold the recipient's details may be omitted (UK £250 under reg 16A, Germany €250 under §33 UStDV), but never for a company: the point of their document is input-tax recovery. `preview_invoice` answers all of the above without allocating anything, so the desk can disable its own button and say why.\n\nEffects: create hospitality.invoice; link hospitality.link.invoice_for_folio; link hospitality.link.invoice_credits_invoice; link hospitality.link.invoice_billed_to_person; link hospitality.link.invoice_billed_to_company; modify hospitality.folio.", "operationId": "apply_hospitality_action_issue_invoice", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "issued_on": { "format": "date", "title": "The property's business date of issue — the document's date for tax purposes, never the wall clock", "type": "string" }, "note": { "title": "Free text printed in the document's footer", "type": "string" }, "recipient_address_override": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "title": "Print this address instead of the profile's", "type": "object" }, "recipient_kind": { "enum": [ "person", "company" ], "title": "Bill the guest or the company. Defaults to the company when the folio was settled to A/R or the reservation carries one, else the guest", "type": "string" }, "recipient_name_override": { "title": "Print this name instead of the profile's — the close-time override Mews exposes as `AccountAddress` / `AccountTaxIdentifier`", "type": "string" }, "recipient_tax_identifier_override": { "title": "Print this tax identifier instead of the profile's", "type": "string" } }, "required": [ "issued_on" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.invoice_for_folio", "hospitality.link.invoice_credits_invoice", "hospitality.link.invoice_billed_to_person", "hospitality.link.invoice_billed_to_company" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.invoice", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.issue_invoice:apply" ] } ], "summary": "Issue invoice", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.issue_invoice/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_issue_invoice` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.issue_invoice:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_issue_invoice", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "issued_on": { "format": "date", "title": "The property's business date of issue — the document's date for tax purposes, never the wall clock", "type": "string" }, "note": { "title": "Free text printed in the document's footer", "type": "string" }, "recipient_address_override": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "title": "Print this address instead of the profile's", "type": "object" }, "recipient_kind": { "enum": [ "person", "company" ], "title": "Bill the guest or the company. Defaults to the company when the folio was settled to A/R or the reservation carries one, else the guest", "type": "string" }, "recipient_name_override": { "title": "Print this name instead of the profile's — the close-time override Mews exposes as `AccountAddress` / `AccountTaxIdentifier`", "type": "string" }, "recipient_tax_identifier_override": { "title": "Print this tax identifier instead of the profile's", "type": "string" } }, "required": [ "issued_on" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.invoice_for_folio", "hospitality.link.invoice_credits_invoice", "hospitality.link.invoice_billed_to_person", "hospitality.link.invoice_billed_to_company" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.invoice", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Issue invoice (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.issue_invoice/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_issue_invoice`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_issue_invoice", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "issued_on": { "format": "date", "title": "The property's business date of issue — the document's date for tax purposes, never the wall clock", "type": "string" }, "note": { "title": "Free text printed in the document's footer", "type": "string" }, "recipient_address_override": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "title": "Print this address instead of the profile's", "type": "object" }, "recipient_kind": { "enum": [ "person", "company" ], "title": "Bill the guest or the company. Defaults to the company when the folio was settled to A/R or the reservation carries one, else the guest", "type": "string" }, "recipient_name_override": { "title": "Print this name instead of the profile's — the close-time override Mews exposes as `AccountAddress` / `AccountTaxIdentifier`", "type": "string" }, "recipient_tax_identifier_override": { "title": "Print this tax identifier instead of the profile's", "type": "string" } }, "required": [ "issued_on" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Issue invoice (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.issue_invoice/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_issue_invoice` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.issue_invoice:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_issue_invoice", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "issued_on": { "format": "date", "title": "The property's business date of issue — the document's date for tax purposes, never the wall clock", "type": "string" }, "note": { "title": "Free text printed in the document's footer", "type": "string" }, "recipient_address_override": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "title": "Print this address instead of the profile's", "type": "object" }, "recipient_kind": { "enum": [ "person", "company" ], "title": "Bill the guest or the company. Defaults to the company when the folio was settled to A/R or the reservation carries one, else the guest", "type": "string" }, "recipient_name_override": { "title": "Print this name instead of the profile's — the close-time override Mews exposes as `AccountAddress` / `AccountTaxIdentifier`", "type": "string" }, "recipient_tax_identifier_override": { "title": "Print this tax identifier instead of the profile's", "type": "string" } }, "required": [ "issued_on" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Issue invoice (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.issue_stock/apply": { "post": { "description": "Record stock leaving a store for use — to a room (room_id), a department, an event — as an `issue` movement, moving the level down by it. Refused when it would take the level below zero, unless the store allows negative stock. Stock used on a fault is logged on its thread (record_work_order_entry); stock moved to another store is transfer_stock.\n\nEffects: create hospitality.stock_movement; create hospitality.stock_level; modify hospitality.stock_level; link hospitality.link.stock_movement_for_level; link hospitality.link.stock_level_for_material; link hospitality.link.stock_level_in_store; link hospitality.link.stock_movement_recorded_by; link hospitality.link.stock_movement_for_room.", "operationId": "apply_hospitality_action_issue_stock", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "material_id": { "format": "uuid", "title": "The material", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "title": "How much left the store, in the material's unit (more than zero)", "type": "string" }, "reason": { "title": "What it was issued for", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When it happened (defaults to now; a handset queueing offline sends its own time; refused when more than five minutes ahead of the kernel's clock)", "type": "string" }, "room_id": { "format": "uuid", "title": "The room it went to", "type": "string", "x-aerandil-references": "hospitality.room" } }, "required": [ "material_id", "quantity" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_store" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.stock_movement_for_level", "hospitality.link.stock_level_for_material", "hospitality.link.stock_level_in_store", "hospitality.link.stock_movement_recorded_by", "hospitality.link.stock_movement_for_room" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.stock_movement", "hospitality.stock_level" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.issue_stock:apply" ] } ], "summary": "Issue stock", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.issue_stock/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_issue_stock` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.issue_stock:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_issue_stock", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "material_id": { "format": "uuid", "title": "The material", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "title": "How much left the store, in the material's unit (more than zero)", "type": "string" }, "reason": { "title": "What it was issued for", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When it happened (defaults to now; a handset queueing offline sends its own time; refused when more than five minutes ahead of the kernel's clock)", "type": "string" }, "room_id": { "format": "uuid", "title": "The room it went to", "type": "string", "x-aerandil-references": "hospitality.room" } }, "required": [ "material_id", "quantity" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_store" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.stock_movement_for_level", "hospitality.link.stock_level_for_material", "hospitality.link.stock_level_in_store", "hospitality.link.stock_movement_recorded_by", "hospitality.link.stock_movement_for_room" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.stock_movement", "hospitality.stock_level" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Issue stock (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.issue_stock/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_issue_stock`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_issue_stock", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "material_id": { "format": "uuid", "title": "The material", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "title": "How much left the store, in the material's unit (more than zero)", "type": "string" }, "reason": { "title": "What it was issued for", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When it happened (defaults to now; a handset queueing offline sends its own time; refused when more than five minutes ahead of the kernel's clock)", "type": "string" }, "room_id": { "format": "uuid", "title": "The room it went to", "type": "string", "x-aerandil-references": "hospitality.room" } }, "required": [ "material_id", "quantity" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_store" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Issue stock (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.issue_stock/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_issue_stock` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.issue_stock:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_issue_stock", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "material_id": { "format": "uuid", "title": "The material", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "title": "How much left the store, in the material's unit (more than zero)", "type": "string" }, "reason": { "title": "What it was issued for", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When it happened (defaults to now; a handset queueing offline sends its own time; refused when more than five minutes ahead of the kernel's clock)", "type": "string" }, "room_id": { "format": "uuid", "title": "The room it went to", "type": "string", "x-aerandil-references": "hospitality.room" } }, "required": [ "material_id", "quantity" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_store" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Issue stock (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.lapse_waitlist_offer/apply": { "post": { "description": "An offer left past its deadline: give its held room-nights back to the ledger and return the entry to `waiting`, stamped `offer_lapsed_at`. The release is what passes the room on — the matcher sees the night free and offers it to the next entry in working order — and the matcher passes over a lapsed entry from then on, so an unanswered phone cannot keep the same room round and round. A no-op on an entry that is not offered or whose deadline has not passed, so a stale or repeated firing is harmless.\n\nEffects: modify hospitality.waitlist_entry; modify hospitality.availability_day.", "operationId": "apply_hospitality_action_lapse_waitlist_offer", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.waitlist_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.waitlist_entry", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.lapse_waitlist_offer:apply" ] } ], "summary": "Lapse waitlist offer", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.lapse_waitlist_offer/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_lapse_waitlist_offer` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.lapse_waitlist_offer:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_lapse_waitlist_offer", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.waitlist_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.waitlist_entry", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Lapse waitlist offer (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.lapse_waitlist_offer/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_lapse_waitlist_offer`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_lapse_waitlist_offer", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.waitlist_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Lapse waitlist offer (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.lapse_waitlist_offer/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_lapse_waitlist_offer` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.lapse_waitlist_offer:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_lapse_waitlist_offer", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.waitlist_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Lapse waitlist offer (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.launch_retail_product_line/apply": { "post": { "description": "Stamp the launch date on a retail product line. Operator verb distinct from object-create — a product line may be created during design and launched commercially later.\n\nEffects: modify hospitality.retail_product_line.", "operationId": "apply_hospitality_action_launch_retail_product_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "launched_on": { "format": "date", "title": "Launch date", "type": "string" } }, "required": [ "launched_on" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.retail_product_line" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.retail_product_line" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.launch_retail_product_line:apply" ] } ], "summary": "Launch retail product line", "tags": [ "brand_venue" ] } }, "/v1/actions/hospitality.action.launch_retail_product_line/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_launch_retail_product_line` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.launch_retail_product_line:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_launch_retail_product_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "launched_on": { "format": "date", "title": "Launch date", "type": "string" } }, "required": [ "launched_on" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.retail_product_line" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.retail_product_line" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Launch retail product line (dry-run)", "tags": [ "brand_venue" ] } }, "/v1/actions/hospitality.action.launch_retail_product_line/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_launch_retail_product_line`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_launch_retail_product_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "launched_on": { "format": "date", "title": "Launch date", "type": "string" } }, "required": [ "launched_on" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.retail_product_line" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Launch retail product line (dry-run)", "tags": [ "brand_venue" ] } }, "/v1/actions/hospitality.action.launch_retail_product_line/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_launch_retail_product_line` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.launch_retail_product_line:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_launch_retail_product_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "launched_on": { "format": "date", "title": "Launch date", "type": "string" } }, "required": [ "launched_on" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.retail_product_line" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Launch retail product line (rollup delta)", "tags": [ "brand_venue" ] } }, "/v1/actions/hospitality.action.lift_rate_restriction/apply": { "post": { "description": "Take one authored restriction off the board: stamps `lifted_at` (business time, defaults to now) and keeps the row as history — the sellability gate, the channel wire and the desk board all treat a lifted row as absent. Lifting a row that is already lifted is a no-op that writes nothing. This is the row-level counterpart of `clear_rate_restrictions`, which opens a window by scope and splices whatever it reaches: a minimum stay lifted with `lift` leaves a stop-sell on the same night standing, where a scoped clear would open both.\n\nEffects: modify hospitality.rate_restriction.", "operationId": "apply_hospitality_action_lift_rate_restriction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "lifted_at": { "format": "date-time", "title": "Business time the restriction was lifted (defaults to now; must not precede posted_at or be in the future)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_restriction" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.rate_restriction" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.lift_rate_restriction:apply" ] } ], "summary": "Lift rate restriction", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.lift_rate_restriction/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_lift_rate_restriction` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.lift_rate_restriction:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_lift_rate_restriction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "lifted_at": { "format": "date-time", "title": "Business time the restriction was lifted (defaults to now; must not precede posted_at or be in the future)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_restriction" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.rate_restriction" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Lift rate restriction (dry-run)", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.lift_rate_restriction/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_lift_rate_restriction`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_lift_rate_restriction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "lifted_at": { "format": "date-time", "title": "Business time the restriction was lifted (defaults to now; must not precede posted_at or be in the future)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_restriction" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Lift rate restriction (dry-run)", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.lift_rate_restriction/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_lift_rate_restriction` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.lift_rate_restriction:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_lift_rate_restriction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "lifted_at": { "format": "date-time", "title": "Business time the restriction was lifted (defaults to now; must not precede posted_at or be in the future)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_restriction" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Lift rate restriction (rollup delta)", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.list_retail_product_at_property/apply": { "post": { "description": "List a retail product as available at the target property (pillow-side amenity, in-room minibar, lobby retail), with effective dates. Same `is_dtc_only` validator as the venue-level listing.\n\nEffects: link hospitality.link.retail_product_available_at_property.", "operationId": "apply_hospitality_action_list_retail_product_at_property", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date-time", "title": "Listing start", "type": "string" }, "effective_to": { "format": "date-time", "title": "Listing end (null when ongoing)", "type": "string" }, "retail_product_id": { "format": "uuid", "title": "Retail product", "type": "string", "x-aerandil-references": "hospitality.retail_product" } }, "required": [ "retail_product_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.retail_product_available_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.list_retail_product_at_property:apply" ] } ], "summary": "List retail product at property", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.list_retail_product_at_property/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_list_retail_product_at_property` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.list_retail_product_at_property:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_list_retail_product_at_property", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date-time", "title": "Listing start", "type": "string" }, "effective_to": { "format": "date-time", "title": "Listing end (null when ongoing)", "type": "string" }, "retail_product_id": { "format": "uuid", "title": "Retail product", "type": "string", "x-aerandil-references": "hospitality.retail_product" } }, "required": [ "retail_product_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.retail_product_available_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview List retail product at property (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.list_retail_product_at_property/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_list_retail_product_at_property`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_list_retail_product_at_property", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date-time", "title": "Listing start", "type": "string" }, "effective_to": { "format": "date-time", "title": "Listing end (null when ongoing)", "type": "string" }, "retail_product_id": { "format": "uuid", "title": "Retail product", "type": "string", "x-aerandil-references": "hospitality.retail_product" } }, "required": [ "retail_product_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate List retail product at property (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.list_retail_product_at_property/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_list_retail_product_at_property` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.list_retail_product_at_property:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_list_retail_product_at_property", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date-time", "title": "Listing start", "type": "string" }, "effective_to": { "format": "date-time", "title": "Listing end (null when ongoing)", "type": "string" }, "retail_product_id": { "format": "uuid", "title": "Retail product", "type": "string", "x-aerandil-references": "hospitality.retail_product" } }, "required": [ "retail_product_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if List retail product at property (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.list_retail_product_at_venue/apply": { "post": { "description": "List a retail product as available at the target venue, with effective dates. Hard validator (proposal 0004 §7) enforces `retail_product.is_dtc_only = false` — DTC-only products cannot be listed in-venue.\n\nEffects: link hospitality.link.retail_product_available_at_venue.", "operationId": "apply_hospitality_action_list_retail_product_at_venue", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date-time", "title": "Listing start", "type": "string" }, "effective_to": { "format": "date-time", "title": "Listing end (null when ongoing)", "type": "string" }, "retail_product_id": { "format": "uuid", "title": "Retail product", "type": "string", "x-aerandil-references": "hospitality.retail_product" } }, "required": [ "retail_product_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.retail_product_available_at_venue" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.list_retail_product_at_venue:apply" ] } ], "summary": "List retail product at venue", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.list_retail_product_at_venue/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_list_retail_product_at_venue` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.list_retail_product_at_venue:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_list_retail_product_at_venue", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date-time", "title": "Listing start", "type": "string" }, "effective_to": { "format": "date-time", "title": "Listing end (null when ongoing)", "type": "string" }, "retail_product_id": { "format": "uuid", "title": "Retail product", "type": "string", "x-aerandil-references": "hospitality.retail_product" } }, "required": [ "retail_product_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.retail_product_available_at_venue" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview List retail product at venue (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.list_retail_product_at_venue/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_list_retail_product_at_venue`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_list_retail_product_at_venue", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date-time", "title": "Listing start", "type": "string" }, "effective_to": { "format": "date-time", "title": "Listing end (null when ongoing)", "type": "string" }, "retail_product_id": { "format": "uuid", "title": "Retail product", "type": "string", "x-aerandil-references": "hospitality.retail_product" } }, "required": [ "retail_product_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate List retail product at venue (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.list_retail_product_at_venue/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_list_retail_product_at_venue` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.list_retail_product_at_venue:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_list_retail_product_at_venue", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date-time", "title": "Listing start", "type": "string" }, "effective_to": { "format": "date-time", "title": "Listing end (null when ongoing)", "type": "string" }, "retail_product_id": { "format": "uuid", "title": "Retail product", "type": "string", "x-aerandil-references": "hospitality.retail_product" } }, "required": [ "retail_product_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if List retail product at venue (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.log_pre_shift_lineup/apply": { "post": { "description": "Record a pre-shift lineup event (or its scheduled-but-skipped absence) for the target venue. High-frequency by design — the shape is the simplest possible event-recording verb so the friction cost doesn't suppress the data the cadence-drift pattern-review query depends on.\n\nEffects: create hospitality.pre_shift_lineup_event; link hospitality.link.lineup_at_venue.", "operationId": "apply_hospitality_action_log_pre_shift_lineup", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "attendance_count": { "title": "Attendance count", "type": "integer" }, "attendance_principals": { "items": { "type": "string" }, "title": "Attendees (staff identifiers)", "type": "array" }, "cancelled": { "title": "Lineup cancelled (scheduled but didn't happen)", "type": "boolean" }, "culture_moment_present": { "title": "Culture moment shared", "type": "boolean" }, "culture_moment_text": { "title": "Culture moment text", "type": "string" }, "duration_seconds": { "title": "Duration in seconds", "type": "integer" }, "leader": { "title": "Leader (staff identifier)", "type": "string" }, "lineup_format": { "enum": [ "group_meeting_15min", "informal_briefing", "one_on_one_per_shift", "none" ], "title": "Lineup format", "type": "string" }, "operational_briefing_present": { "title": "Operational briefing covered", "type": "boolean" }, "operational_briefing_summary": { "title": "Operational briefing summary", "type": "string" }, "standards_reinforcement_topic": { "title": "Standards reinforcement topic", "type": "string" }, "started_at": { "format": "date-time", "title": "When the lineup started", "type": "string" } }, "required": [ "started_at", "duration_seconds", "leader", "attendance_count", "culture_moment_present", "operational_briefing_present", "cancelled", "lineup_format" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.lineup_at_venue" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.pre_shift_lineup_event" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.log_pre_shift_lineup:apply" ] } ], "summary": "Log pre-shift lineup", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.log_pre_shift_lineup/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_log_pre_shift_lineup` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.log_pre_shift_lineup:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_log_pre_shift_lineup", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "attendance_count": { "title": "Attendance count", "type": "integer" }, "attendance_principals": { "items": { "type": "string" }, "title": "Attendees (staff identifiers)", "type": "array" }, "cancelled": { "title": "Lineup cancelled (scheduled but didn't happen)", "type": "boolean" }, "culture_moment_present": { "title": "Culture moment shared", "type": "boolean" }, "culture_moment_text": { "title": "Culture moment text", "type": "string" }, "duration_seconds": { "title": "Duration in seconds", "type": "integer" }, "leader": { "title": "Leader (staff identifier)", "type": "string" }, "lineup_format": { "enum": [ "group_meeting_15min", "informal_briefing", "one_on_one_per_shift", "none" ], "title": "Lineup format", "type": "string" }, "operational_briefing_present": { "title": "Operational briefing covered", "type": "boolean" }, "operational_briefing_summary": { "title": "Operational briefing summary", "type": "string" }, "standards_reinforcement_topic": { "title": "Standards reinforcement topic", "type": "string" }, "started_at": { "format": "date-time", "title": "When the lineup started", "type": "string" } }, "required": [ "started_at", "duration_seconds", "leader", "attendance_count", "culture_moment_present", "operational_briefing_present", "cancelled", "lineup_format" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.lineup_at_venue" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.pre_shift_lineup_event" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Log pre-shift lineup (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.log_pre_shift_lineup/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_log_pre_shift_lineup`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_log_pre_shift_lineup", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "attendance_count": { "title": "Attendance count", "type": "integer" }, "attendance_principals": { "items": { "type": "string" }, "title": "Attendees (staff identifiers)", "type": "array" }, "cancelled": { "title": "Lineup cancelled (scheduled but didn't happen)", "type": "boolean" }, "culture_moment_present": { "title": "Culture moment shared", "type": "boolean" }, "culture_moment_text": { "title": "Culture moment text", "type": "string" }, "duration_seconds": { "title": "Duration in seconds", "type": "integer" }, "leader": { "title": "Leader (staff identifier)", "type": "string" }, "lineup_format": { "enum": [ "group_meeting_15min", "informal_briefing", "one_on_one_per_shift", "none" ], "title": "Lineup format", "type": "string" }, "operational_briefing_present": { "title": "Operational briefing covered", "type": "boolean" }, "operational_briefing_summary": { "title": "Operational briefing summary", "type": "string" }, "standards_reinforcement_topic": { "title": "Standards reinforcement topic", "type": "string" }, "started_at": { "format": "date-time", "title": "When the lineup started", "type": "string" } }, "required": [ "started_at", "duration_seconds", "leader", "attendance_count", "culture_moment_present", "operational_briefing_present", "cancelled", "lineup_format" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Log pre-shift lineup (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.log_pre_shift_lineup/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_log_pre_shift_lineup` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.log_pre_shift_lineup:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_log_pre_shift_lineup", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "attendance_count": { "title": "Attendance count", "type": "integer" }, "attendance_principals": { "items": { "type": "string" }, "title": "Attendees (staff identifiers)", "type": "array" }, "cancelled": { "title": "Lineup cancelled (scheduled but didn't happen)", "type": "boolean" }, "culture_moment_present": { "title": "Culture moment shared", "type": "boolean" }, "culture_moment_text": { "title": "Culture moment text", "type": "string" }, "duration_seconds": { "title": "Duration in seconds", "type": "integer" }, "leader": { "title": "Leader (staff identifier)", "type": "string" }, "lineup_format": { "enum": [ "group_meeting_15min", "informal_briefing", "one_on_one_per_shift", "none" ], "title": "Lineup format", "type": "string" }, "operational_briefing_present": { "title": "Operational briefing covered", "type": "boolean" }, "operational_briefing_summary": { "title": "Operational briefing summary", "type": "string" }, "standards_reinforcement_topic": { "title": "Standards reinforcement topic", "type": "string" }, "started_at": { "format": "date-time", "title": "When the lineup started", "type": "string" } }, "required": [ "started_at", "duration_seconds", "leader", "attendance_count", "culture_moment_present", "operational_briefing_present", "cancelled", "lineup_format" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Log pre-shift lineup (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.map_channel_inventory/apply": { "post": { "description": "Bind one of our room types or rate plans to the code the partner knows it by. Upsert on (conduit, mapping kind, our room type / rate plan): re-mapping closes the prior binding with `effective_to` and mints a fresh row, so the history of what was published under which code survives. `included_occupancy` is load-bearing under occupancy-based pricing — a rate push that omits the occupancy level matching the partner's configured included occupancy is silently not applied, with no error and no price. The first mapping on a `pending_mapping` conduit promotes it to `active`. Emits `channel_mapping.mapped`.\n\nEffects: create hospitality.channel_mapping; modify hospitality.channel_mapping; modify hospitality.channel_connection; link hospitality.link.channel_mapping_for_connection; link hospitality.link.channel_mapping_for_room_type; link hospitality.link.channel_mapping_for_rate_plan.", "operationId": "apply_hospitality_action_map_channel_inventory", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date", "title": "First date this binding applies", "type": "string" }, "external_code": { "title": "The partner's code for this room type / rate plan", "type": "string" }, "external_name": { "title": "The partner's display name for it (drift check against their config)", "type": "string" }, "included_occupancy": { "title": "Adult occupancy the partner's price is quoted for", "type": "integer" }, "mapping_kind": { "enum": [ "room_type", "rate_plan", "room_rate", "age_category", "extra" ], "title": "What this row binds", "type": "string" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "publish_rates": { "title": "Publish rate amounts for this binding (default true)", "type": "boolean" }, "publish_restrictions": { "title": "Publish restrictions for this binding (default true)", "type": "boolean" }, "rate_plan_id": { "format": "uuid", "title": "Our rate plan (required for rate_plan and room_rate kinds)", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Our room type (required for room_type and room_rate kinds)", "type": "string", "x-aerandil-references": "hospitality.room_type" } }, "required": [ "mapping_kind", "external_code", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.channel_mapping_for_connection", "hospitality.link.channel_mapping_for_room_type", "hospitality.link.channel_mapping_for_rate_plan" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.channel_mapping", "hospitality.channel_connection" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.map_channel_inventory:apply" ] } ], "summary": "Map channel inventory", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.map_channel_inventory/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_map_channel_inventory` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.map_channel_inventory:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_map_channel_inventory", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date", "title": "First date this binding applies", "type": "string" }, "external_code": { "title": "The partner's code for this room type / rate plan", "type": "string" }, "external_name": { "title": "The partner's display name for it (drift check against their config)", "type": "string" }, "included_occupancy": { "title": "Adult occupancy the partner's price is quoted for", "type": "integer" }, "mapping_kind": { "enum": [ "room_type", "rate_plan", "room_rate", "age_category", "extra" ], "title": "What this row binds", "type": "string" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "publish_rates": { "title": "Publish rate amounts for this binding (default true)", "type": "boolean" }, "publish_restrictions": { "title": "Publish restrictions for this binding (default true)", "type": "boolean" }, "rate_plan_id": { "format": "uuid", "title": "Our rate plan (required for rate_plan and room_rate kinds)", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Our room type (required for room_type and room_rate kinds)", "type": "string", "x-aerandil-references": "hospitality.room_type" } }, "required": [ "mapping_kind", "external_code", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.channel_mapping_for_connection", "hospitality.link.channel_mapping_for_room_type", "hospitality.link.channel_mapping_for_rate_plan" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.channel_mapping", "hospitality.channel_connection" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Map channel inventory (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.map_channel_inventory/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_map_channel_inventory`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_map_channel_inventory", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date", "title": "First date this binding applies", "type": "string" }, "external_code": { "title": "The partner's code for this room type / rate plan", "type": "string" }, "external_name": { "title": "The partner's display name for it (drift check against their config)", "type": "string" }, "included_occupancy": { "title": "Adult occupancy the partner's price is quoted for", "type": "integer" }, "mapping_kind": { "enum": [ "room_type", "rate_plan", "room_rate", "age_category", "extra" ], "title": "What this row binds", "type": "string" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "publish_rates": { "title": "Publish rate amounts for this binding (default true)", "type": "boolean" }, "publish_restrictions": { "title": "Publish restrictions for this binding (default true)", "type": "boolean" }, "rate_plan_id": { "format": "uuid", "title": "Our rate plan (required for rate_plan and room_rate kinds)", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Our room type (required for room_type and room_rate kinds)", "type": "string", "x-aerandil-references": "hospitality.room_type" } }, "required": [ "mapping_kind", "external_code", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Map channel inventory (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.map_channel_inventory/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_map_channel_inventory` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.map_channel_inventory:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_map_channel_inventory", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_from": { "format": "date", "title": "First date this binding applies", "type": "string" }, "external_code": { "title": "The partner's code for this room type / rate plan", "type": "string" }, "external_name": { "title": "The partner's display name for it (drift check against their config)", "type": "string" }, "included_occupancy": { "title": "Adult occupancy the partner's price is quoted for", "type": "integer" }, "mapping_kind": { "enum": [ "room_type", "rate_plan", "room_rate", "age_category", "extra" ], "title": "What this row binds", "type": "string" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "publish_rates": { "title": "Publish rate amounts for this binding (default true)", "type": "boolean" }, "publish_restrictions": { "title": "Publish restrictions for this binding (default true)", "type": "boolean" }, "rate_plan_id": { "format": "uuid", "title": "Our rate plan (required for rate_plan and room_rate kinds)", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Our room type (required for room_type and room_rate kinds)", "type": "string", "x-aerandil-references": "hospitality.room_type" } }, "required": [ "mapping_kind", "external_code", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Map channel inventory (rollup delta)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.mark_appointment_no_show/apply": { "post": { "description": "Mark a booked / confirmed appointment as a no-show — the guest never arrived. Distinct from cancel_appointment because no-show is its own operating KPI in every major spa system (Mindbody, Square, Zenoti). The instant lands in `cancelled_at` (the shared did-not-happen stamp); `cancellation_kind` stays absent — no_show is a status, not a cancellation flavour. Fee posting is not automated (same posture as cancel). Emits `spa.appointment_no_show`.\n\nEffects: modify hospitality.appointment.", "operationId": "apply_hospitality_action_mark_appointment_no_show", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "marked_at": { "format": "date-time", "title": "When the no-show was recorded (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.appointment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.mark_appointment_no_show:apply" ] } ], "summary": "Mark appointment no-show", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.mark_appointment_no_show/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_mark_appointment_no_show` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.mark_appointment_no_show:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_mark_appointment_no_show", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "marked_at": { "format": "date-time", "title": "When the no-show was recorded (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.appointment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Mark appointment no-show (dry-run)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.mark_appointment_no_show/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_mark_appointment_no_show`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_mark_appointment_no_show", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "marked_at": { "format": "date-time", "title": "When the no-show was recorded (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Mark appointment no-show (dry-run)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.mark_appointment_no_show/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_mark_appointment_no_show` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.mark_appointment_no_show:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_mark_appointment_no_show", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "marked_at": { "format": "date-time", "title": "When the no-show was recorded (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Mark appointment no-show (rollup delta)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.mark_request_overdue/apply": { "post": { "description": "Stamp `overdue_at` on a request whose due time has passed with the work still open — the effect of the standing `request_overdue` sweep (every five minutes over open tasks with a due time passed and no stamp yet), callable by hand too. Refused when the task has no `due_at` or its time has not passed; a finished or skipped task, or one already stamped, is a no-op. Emits `housekeeping.task.overdue` once, which the `task_overdue` push rides to the holder — the group's members when a group holds it, the house's supervisors when nobody does.\n\nEffects: modify hospitality.housekeeping_task.", "operationId": "apply_hospitality_action_mark_request_overdue", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.mark_request_overdue:apply" ] } ], "summary": "Mark request overdue", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.mark_request_overdue/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_mark_request_overdue` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.mark_request_overdue:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_mark_request_overdue", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Mark request overdue (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.mark_request_overdue/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_mark_request_overdue`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_mark_request_overdue", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Mark request overdue (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.mark_request_overdue/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_mark_request_overdue` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.mark_request_overdue:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_mark_request_overdue", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Mark request overdue (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.mark_reservation_no_show/apply": { "post": { "description": "Record that the guest never arrived: reservation to the terminal no_show state, its room slices to cancelled, and their room-nights released back to the availability ledger from `as_of` — the business day the no-show belongs to, the arrival day the audit closed, never after the house's today — or, when it is not given, from the house's today forward: the hotel date (the business date the property has open, else its local calendar day). A no-show recorded after the fact without `as_of` therefore releases nothing: its nights have passed. Normally driven during the night-audit sweep of the arrival business day, which passes the day it is closing. Posts the house's no-show posting rule for the booking's guarantee onto its own account, as the audit's sweep does, so a booking the desk marks before the close is posted the same as one the close marks. Guest-impacting and terminal, so agents stage it for human confirmation.\n\nEffects: modify hospitality.reservation; modify hospitality.reservation_room; modify hospitality.availability_day; modify hospitality.share_group; unlink hospitality.link.reservation_in_share_group; modify hospitality.payment_request; create hospitality.folio; modify hospitality.folio; link hospitality.link.reservation_has_folio; create hospitality.charge; link hospitality.link.folio_has_charge; link hospitality.link.charge_at_outlet; link hospitality.link.charge_for_service_item; create hospitality.tax_application; link hospitality.link.charge_has_tax_application; create hospitality.payment; link hospitality.link.folio_has_payment.", "operationId": "apply_hospitality_action_mark_reservation_no_show", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "as_of": { "format": "date", "title": "As of", "type": "string" }, "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated", "linked" ] }, "link_type": { "enum": [ "hospitality.link.reservation_in_share_group", "hospitality.link.reservation_has_folio", "hospitality.link.folio_has_charge", "hospitality.link.charge_at_outlet", "hospitality.link.charge_for_service_item", "hospitality.link.charge_has_tax_application", "hospitality.link.folio_has_payment" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.reservation", "hospitality.reservation_room", "hospitality.availability_day", "hospitality.share_group", "hospitality.payment_request", "hospitality.folio", "hospitality.charge", "hospitality.tax_application", "hospitality.payment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.mark_reservation_no_show:apply" ] } ], "summary": "Mark reservation no-show", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.mark_reservation_no_show/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_mark_reservation_no_show` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.mark_reservation_no_show:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_mark_reservation_no_show", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "as_of": { "format": "date", "title": "As of", "type": "string" }, "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated", "linked" ] }, "link_type": { "enum": [ "hospitality.link.reservation_in_share_group", "hospitality.link.reservation_has_folio", "hospitality.link.folio_has_charge", "hospitality.link.charge_at_outlet", "hospitality.link.charge_for_service_item", "hospitality.link.charge_has_tax_application", "hospitality.link.folio_has_payment" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.reservation", "hospitality.reservation_room", "hospitality.availability_day", "hospitality.share_group", "hospitality.payment_request", "hospitality.folio", "hospitality.charge", "hospitality.tax_application", "hospitality.payment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Mark reservation no-show (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.mark_reservation_no_show/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_mark_reservation_no_show`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_mark_reservation_no_show", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "as_of": { "format": "date", "title": "As of", "type": "string" }, "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Mark reservation no-show (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.mark_reservation_no_show/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_mark_reservation_no_show` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.mark_reservation_no_show:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_mark_reservation_no_show", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "as_of": { "format": "date", "title": "As of", "type": "string" }, "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Mark reservation no-show (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.match_waitlist_entries/apply": { "post": { "description": "Offer a freed room-night to the waitlist. Takes the ledger row that moved; reads its room type's waiting entries in working order (priority, then requested_at, then id) and offers every one whose whole stay the house can now take — the selling ceiling on every ledger night, the rate plan's stay window and the restriction wall, exactly what accept will check — each offer holding its nights until the property's offer deadline, so the next entry is judged against what the last one left. Passes over entries already offered, entries whose offer once lapsed (the desk can still offer them), `guest_request` entries (a need the ledger cannot see) and arrivals already past. The automation lane fires it when a night's headroom rises: a cancellation, a no-show, a block or offer released, a room back in order, more rooms on sale. A no-op when nothing clears.\n\nEffects: modify hospitality.waitlist_entry; modify hospitality.availability_day; create hospitality.guest_message; create hospitality.guest_conversation; modify hospitality.guest_conversation; link hospitality.link.guest_conversation_for_person; link hospitality.link.guest_conversation_at_property; link hospitality.link.guest_conversation_anchored_to_reservation; link hospitality.link.guest_message_in_conversation.", "operationId": "apply_hospitality_action_match_waitlist_entries", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.availability_day" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.guest_conversation_for_person", "hospitality.link.guest_conversation_at_property", "hospitality.link.guest_conversation_anchored_to_reservation", "hospitality.link.guest_message_in_conversation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.waitlist_entry", "hospitality.availability_day", "hospitality.guest_message", "hospitality.guest_conversation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.match_waitlist_entries:apply" ] } ], "summary": "Match waitlist entries", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.match_waitlist_entries/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_match_waitlist_entries` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.match_waitlist_entries:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_match_waitlist_entries", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.availability_day" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.guest_conversation_for_person", "hospitality.link.guest_conversation_at_property", "hospitality.link.guest_conversation_anchored_to_reservation", "hospitality.link.guest_message_in_conversation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.waitlist_entry", "hospitality.availability_day", "hospitality.guest_message", "hospitality.guest_conversation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Match waitlist entries (dry-run)", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.match_waitlist_entries/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_match_waitlist_entries`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_match_waitlist_entries", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.availability_day" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Match waitlist entries (dry-run)", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.match_waitlist_entries/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_match_waitlist_entries` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.match_waitlist_entries:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_match_waitlist_entries", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.availability_day" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Match waitlist entries (rollup delta)", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.materialise_channel_mix_snapshot/apply": { "post": { "description": "Compute and persist a channel-mix snapshot for the target property on a given business date + cadence. The snapshot is immutable post-write; re-runs require explicit deletion of the prior row.\n\nEffects: create hospitality.channel_mix_snapshot; link hospitality.link.property_has_channel_mix_snapshot.", "operationId": "apply_hospitality_action_materialise_channel_mix_snapshot", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" }, "cadence": { "enum": [ "daily", "weekly", "monthly" ], "title": "Cadence", "type": "string" }, "direct_share_observed": { "format": "decimal", "title": "Direct share (decimal 0..=1)", "type": "string" }, "gds_share_observed": { "format": "decimal", "title": "GDS share (decimal 0..=1)", "type": "string" }, "ota_share_observed": { "format": "decimal", "title": "OTA share (decimal 0..=1)", "type": "string" }, "per_channel": { "title": "Per-channel contributions" } }, "required": [ "business_date", "cadence", "per_channel", "direct_share_observed", "ota_share_observed", "gds_share_observed" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.property_has_channel_mix_snapshot" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.channel_mix_snapshot" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.materialise_channel_mix_snapshot:apply" ] } ], "summary": "Materialise channel-mix snapshot", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.materialise_channel_mix_snapshot/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_materialise_channel_mix_snapshot` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.materialise_channel_mix_snapshot:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_materialise_channel_mix_snapshot", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" }, "cadence": { "enum": [ "daily", "weekly", "monthly" ], "title": "Cadence", "type": "string" }, "direct_share_observed": { "format": "decimal", "title": "Direct share (decimal 0..=1)", "type": "string" }, "gds_share_observed": { "format": "decimal", "title": "GDS share (decimal 0..=1)", "type": "string" }, "ota_share_observed": { "format": "decimal", "title": "OTA share (decimal 0..=1)", "type": "string" }, "per_channel": { "title": "Per-channel contributions" } }, "required": [ "business_date", "cadence", "per_channel", "direct_share_observed", "ota_share_observed", "gds_share_observed" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.property_has_channel_mix_snapshot" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.channel_mix_snapshot" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Materialise channel-mix snapshot (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.materialise_channel_mix_snapshot/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_materialise_channel_mix_snapshot`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_materialise_channel_mix_snapshot", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" }, "cadence": { "enum": [ "daily", "weekly", "monthly" ], "title": "Cadence", "type": "string" }, "direct_share_observed": { "format": "decimal", "title": "Direct share (decimal 0..=1)", "type": "string" }, "gds_share_observed": { "format": "decimal", "title": "GDS share (decimal 0..=1)", "type": "string" }, "ota_share_observed": { "format": "decimal", "title": "OTA share (decimal 0..=1)", "type": "string" }, "per_channel": { "title": "Per-channel contributions" } }, "required": [ "business_date", "cadence", "per_channel", "direct_share_observed", "ota_share_observed", "gds_share_observed" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Materialise channel-mix snapshot (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.materialise_channel_mix_snapshot/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_materialise_channel_mix_snapshot` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.materialise_channel_mix_snapshot:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_materialise_channel_mix_snapshot", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" }, "cadence": { "enum": [ "daily", "weekly", "monthly" ], "title": "Cadence", "type": "string" }, "direct_share_observed": { "format": "decimal", "title": "Direct share (decimal 0..=1)", "type": "string" }, "gds_share_observed": { "format": "decimal", "title": "GDS share (decimal 0..=1)", "type": "string" }, "ota_share_observed": { "format": "decimal", "title": "OTA share (decimal 0..=1)", "type": "string" }, "per_channel": { "title": "Per-channel contributions" } }, "required": [ "business_date", "cadence", "per_channel", "direct_share_observed", "ota_share_observed", "gds_share_observed" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Materialise channel-mix snapshot (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.materialise_derived_rate/apply": { "post": { "description": "Compute and snapshot the effective rate for a (rate_plan, room_type, business_date) at `effective_at`. Idempotent on the four-key tuple; supersedes prior snapshots for the same (rate_plan, room_type, business_date).\n\nEffects: create hospitality.derived_rate; modify hospitality.derived_rate; link hospitality.link.derived_rate_for_rate_plan; link hospitality.link.derived_rate_for_room_type; link hospitality.link.derived_rate_for_rate_per_night.", "operationId": "apply_hospitality_action_materialise_derived_rate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" }, "effective_at": { "format": "date-time", "title": "Snapshot timestamp", "type": "string" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type", "type": "string", "x-aerandil-references": "hospitality.room_type" } }, "required": [ "rate_plan_id", "room_type_id", "business_date", "effective_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.derived_rate_for_rate_plan", "hospitality.link.derived_rate_for_room_type", "hospitality.link.derived_rate_for_rate_per_night" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.derived_rate" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.materialise_derived_rate:apply" ] } ], "summary": "Materialise derived rate", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.materialise_derived_rate/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_materialise_derived_rate` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.materialise_derived_rate:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_materialise_derived_rate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" }, "effective_at": { "format": "date-time", "title": "Snapshot timestamp", "type": "string" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type", "type": "string", "x-aerandil-references": "hospitality.room_type" } }, "required": [ "rate_plan_id", "room_type_id", "business_date", "effective_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.derived_rate_for_rate_plan", "hospitality.link.derived_rate_for_room_type", "hospitality.link.derived_rate_for_rate_per_night" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.derived_rate" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Materialise derived rate (dry-run)", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.materialise_derived_rate/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_materialise_derived_rate`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_materialise_derived_rate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" }, "effective_at": { "format": "date-time", "title": "Snapshot timestamp", "type": "string" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type", "type": "string", "x-aerandil-references": "hospitality.room_type" } }, "required": [ "rate_plan_id", "room_type_id", "business_date", "effective_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Materialise derived rate (dry-run)", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.materialise_derived_rate/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_materialise_derived_rate` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.materialise_derived_rate:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_materialise_derived_rate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" }, "effective_at": { "format": "date-time", "title": "Snapshot timestamp", "type": "string" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type", "type": "string", "x-aerandil-references": "hospitality.room_type" } }, "required": [ "rate_plan_id", "room_type_id", "business_date", "effective_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Materialise derived rate (rollup delta)", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.message_guest/apply": { "post": { "description": "Write to a guest the house has not heard from, or write first in a conversation they already have: by SMS to the profile's mobile number or by email to its address. With no `channel`, the kernel takes the first the guest can be reached on — a text when the profile holds a mobile number the guest has not stopped, else an email. The message lands in the guest's conversation at the house (opened when they have none) and is queued for the kernel's delivery adapter, which sends it after commit and records what happened. Refused when the profile holds no contact for the channel, when the guest asked for erasure or texted STOP in any conversation at the house, and — for a marketing message — when the profile holds no live marketing consent for the channel or the guest opted out of marketing there. A service message (the default) needs no marketing consent.\n\nEffects: create hospitality.guest_message; create hospitality.guest_conversation; modify hospitality.guest_conversation; link hospitality.link.guest_conversation_for_person; link hospitality.link.guest_conversation_at_property; link hospitality.link.guest_conversation_anchored_to_reservation; link hospitality.link.guest_message_in_conversation.", "operationId": "apply_hospitality_action_message_guest", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "anchor_reservation_id": { "format": "uuid", "title": "The stay the message is about, when it opens a conversation", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "body": { "title": "What the message says", "type": "string" }, "channel": { "enum": [ "sms", "email" ], "title": "sms or email; omitted, the first the guest can be reached on (a text, else an email)", "type": "string" }, "person_id": { "format": "uuid", "title": "The guest", "type": "string", "x-aerandil-references": "hospitality.person" }, "purpose": { "enum": [ "service", "marketing" ], "title": "service (the default) or marketing", "type": "string" } }, "required": [ "person_id", "body" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.guest_conversation_for_person", "hospitality.link.guest_conversation_at_property", "hospitality.link.guest_conversation_anchored_to_reservation", "hospitality.link.guest_message_in_conversation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.guest_message", "hospitality.guest_conversation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.message_guest:apply" ] } ], "summary": "Message guest", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.message_guest/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_message_guest` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.message_guest:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_message_guest", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "anchor_reservation_id": { "format": "uuid", "title": "The stay the message is about, when it opens a conversation", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "body": { "title": "What the message says", "type": "string" }, "channel": { "enum": [ "sms", "email" ], "title": "sms or email; omitted, the first the guest can be reached on (a text, else an email)", "type": "string" }, "person_id": { "format": "uuid", "title": "The guest", "type": "string", "x-aerandil-references": "hospitality.person" }, "purpose": { "enum": [ "service", "marketing" ], "title": "service (the default) or marketing", "type": "string" } }, "required": [ "person_id", "body" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.guest_conversation_for_person", "hospitality.link.guest_conversation_at_property", "hospitality.link.guest_conversation_anchored_to_reservation", "hospitality.link.guest_message_in_conversation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.guest_message", "hospitality.guest_conversation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Message guest (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.message_guest/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_message_guest`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_message_guest", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "anchor_reservation_id": { "format": "uuid", "title": "The stay the message is about, when it opens a conversation", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "body": { "title": "What the message says", "type": "string" }, "channel": { "enum": [ "sms", "email" ], "title": "sms or email; omitted, the first the guest can be reached on (a text, else an email)", "type": "string" }, "person_id": { "format": "uuid", "title": "The guest", "type": "string", "x-aerandil-references": "hospitality.person" }, "purpose": { "enum": [ "service", "marketing" ], "title": "service (the default) or marketing", "type": "string" } }, "required": [ "person_id", "body" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Message guest (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.message_guest/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_message_guest` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.message_guest:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_message_guest", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "anchor_reservation_id": { "format": "uuid", "title": "The stay the message is about, when it opens a conversation", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "body": { "title": "What the message says", "type": "string" }, "channel": { "enum": [ "sms", "email" ], "title": "sms or email; omitted, the first the guest can be reached on (a text, else an email)", "type": "string" }, "person_id": { "format": "uuid", "title": "The guest", "type": "string", "x-aerandil-references": "hospitality.person" }, "purpose": { "enum": [ "service", "marketing" ], "title": "service (the default) or marketing", "type": "string" } }, "required": [ "person_id", "body" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Message guest (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.modify_reservation_dates/apply": { "post": { "description": "Change a reservation's stay window — the single most common front-desk write. Pre-arrival (held / confirmed / modified) both dates move; in-house only the departure moves (extend or shorten — never below the house's today, the hotel date, and never touching nights already slept). Every leg's nights are re-derived: surviving nights stay, dropped nights soft-delete and release their room-nights back to the availability ledger, added nights mint, consume availability (a sold-out night refuses the whole change atomically, naming the night), and price per the required pricing_policy. Re-applying with the current dates and keep_rate is a no-op; the same dates with requote / override is an explicit in-place re-price. The reservation's rate-plan stay-length window re-checks, and pre-arrival changes re-run the full restriction gate for the new window. A day-use reservation (zero-night window on a day-use plan) moves its slot date but keeps the zero-night shape; keep_rate keeps the leg's slot rate, override re-prices it, and the requote kinds refuse (no per-night grid exists for a day slot).\n\nEffects: modify hospitality.reservation; modify hospitality.reservation_room; modify hospitality.availability_day; create hospitality.reservation_night; modify hospitality.reservation_night; delete hospitality.reservation_night; link hospitality.link.reservation_room_has_night; link hospitality.link.reservation_night_uses_rate_plan; modify hospitality.payment_request.\n\nStep-up when `pricing_policy` is `override`: a person (a `User` principal) needs a fresh desk step-up proof — Pricing nights at a typed-in rate overrides the house's published price — or the call is refused `403 step_up_required` before anything runs. Re-enter the passcode at `POST /v1/desk/sessions/{id}/passcode` and retry. Machine principals are not gated.", "operationId": "apply_hospitality_action_modify_reservation_dates", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "new_arrival_date": { "format": "date", "title": "New arrival date", "type": "string" }, "new_departure_date": { "format": "date", "title": "New departure date", "type": "string" }, "override_nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate for pricing_policy = override", "type": "object" }, "override_reason": { "title": "Why the override price (required with pricing_policy = override)", "type": "string" }, "pricing_policy": { "enum": [ "keep_rate", "requote", "requote_added_nights_only", "override" ], "title": "How affected nights re-price (required; never silent)", "type": "string" } }, "required": [ "new_arrival_date", "new_departure_date", "pricing_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.reservation_room_has_night", "hospitality.link.reservation_night_uses_rate_plan" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created", "deleted" ] }, "object_type": { "enum": [ "hospitality.reservation", "hospitality.reservation_room", "hospitality.availability_day", "hospitality.reservation_night", "hospitality.payment_request" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "403": { "description": "`step_up_required` — a person applied this without a fresh desk step-up proof; nothing ran." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.modify_reservation_dates:apply" ] } ], "summary": "Modify reservation dates", "tags": [ "booking" ], "x-aerandil-step-up": { "reason": "Pricing nights at a typed-in rate overrides the house's published price", "when": { "kind": "param_equals", "param": "pricing_policy", "value": "override" } } } }, "/v1/actions/hospitality.action.modify_reservation_dates/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_modify_reservation_dates` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.modify_reservation_dates:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_modify_reservation_dates", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "new_arrival_date": { "format": "date", "title": "New arrival date", "type": "string" }, "new_departure_date": { "format": "date", "title": "New departure date", "type": "string" }, "override_nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate for pricing_policy = override", "type": "object" }, "override_reason": { "title": "Why the override price (required with pricing_policy = override)", "type": "string" }, "pricing_policy": { "enum": [ "keep_rate", "requote", "requote_added_nights_only", "override" ], "title": "How affected nights re-price (required; never silent)", "type": "string" } }, "required": [ "new_arrival_date", "new_departure_date", "pricing_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.reservation_room_has_night", "hospitality.link.reservation_night_uses_rate_plan" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created", "deleted" ] }, "object_type": { "enum": [ "hospitality.reservation", "hospitality.reservation_room", "hospitality.availability_day", "hospitality.reservation_night", "hospitality.payment_request" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Modify reservation dates (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.modify_reservation_dates/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_modify_reservation_dates`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_modify_reservation_dates", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "new_arrival_date": { "format": "date", "title": "New arrival date", "type": "string" }, "new_departure_date": { "format": "date", "title": "New departure date", "type": "string" }, "override_nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate for pricing_policy = override", "type": "object" }, "override_reason": { "title": "Why the override price (required with pricing_policy = override)", "type": "string" }, "pricing_policy": { "enum": [ "keep_rate", "requote", "requote_added_nights_only", "override" ], "title": "How affected nights re-price (required; never silent)", "type": "string" } }, "required": [ "new_arrival_date", "new_departure_date", "pricing_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Modify reservation dates (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.modify_reservation_dates/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_modify_reservation_dates` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.modify_reservation_dates:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_modify_reservation_dates", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "new_arrival_date": { "format": "date", "title": "New arrival date", "type": "string" }, "new_departure_date": { "format": "date", "title": "New departure date", "type": "string" }, "override_nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate for pricing_policy = override", "type": "object" }, "override_reason": { "title": "Why the override price (required with pricing_policy = override)", "type": "string" }, "pricing_policy": { "enum": [ "keep_rate", "requote", "requote_added_nights_only", "override" ], "title": "How affected nights re-price (required; never silent)", "type": "string" } }, "required": [ "new_arrival_date", "new_departure_date", "pricing_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Modify reservation dates (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.move_room/apply": { "post": { "description": "Move an in-house guest to another room in one atomic verb (pre-check-in moves are assign_room_for_reservation_room). The target room must be vacant, in the same property, and not out-of-order for the remaining stay; a dirty or pickup room needs an explicit allow_dirty_room acknowledgment. On a cross-type move the remaining (unslept) nights settle the availability ledger atomically — a sold-out night refuses the whole move, naming the night — and the required pricing_policy decides the money: keep_rate pins reservation_room_charged_as_room_type (the comp upgrade — the guest sleeps in the new type, keeps paying the old one); requote re-prices remaining nights from the new type's published grid; override takes the supplied rate with its reason. The old room is vacated into a declared housekeeping status (old_room_status, default dirty), the new room becomes occupied, and the emitted event is the permanent move history.\n\nEffects: modify hospitality.room; modify hospitality.availability_day; modify hospitality.reservation_night; modify hospitality.room_discrepancy; link hospitality.link.stay_in_room; unlink hospitality.link.stay_in_room; link hospitality.link.reservation_room_assigned_to; unlink hospitality.link.reservation_room_assigned_to; link hospitality.link.reservation_room_for_room_type; unlink hospitality.link.reservation_room_for_room_type; link hospitality.link.reservation_room_charged_as_room_type; unlink hospitality.link.reservation_room_charged_as_room_type.\n\nStep-up when `pricing_policy` is `override`: a person (a `User` principal) needs a fresh desk step-up proof — Pricing nights at a typed-in rate overrides the house's published price — or the call is refused `403 step_up_required` before anything runs. Re-enter the passcode at `POST /v1/desk/sessions/{id}/passcode` and retry. Machine principals are not gated.", "operationId": "apply_hospitality_action_move_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allow_dirty_room": { "title": "Acknowledge moving into a dirty / pickup room", "type": "boolean" }, "new_room_id": { "format": "uuid", "title": "Room to move the guest into", "type": "string", "x-aerandil-references": "hospitality.room" }, "old_room_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Housekeeping status the vacated room lands in (default dirty)", "type": "string" }, "override_nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate for pricing_policy = override", "type": "object" }, "override_reason": { "title": "Why the override price (required with pricing_policy = override)", "type": "string" }, "pricing_policy": { "enum": [ "keep_rate", "requote", "requote_added_nights_only", "override" ], "title": "How affected nights re-price (required; never silent)", "type": "string" }, "reason": { "title": "Why the guest is moving (noise complaint, maintenance, upsell)", "type": "string" }, "reservation_room_id": { "format": "uuid", "title": "Leg being moved (required when the reservation has more than one reservation_room)", "type": "string", "x-aerandil-references": "hospitality.reservation_room" } }, "required": [ "new_room_id", "pricing_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.stay_in_room", "hospitality.link.reservation_room_assigned_to", "hospitality.link.reservation_room_for_room_type", "hospitality.link.reservation_room_charged_as_room_type" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.room", "hospitality.availability_day", "hospitality.reservation_night", "hospitality.room_discrepancy" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "403": { "description": "`step_up_required` — a person applied this without a fresh desk step-up proof; nothing ran." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.move_room:apply" ] } ], "summary": "Move room (in-house)", "tags": [ "booking" ], "x-aerandil-step-up": { "reason": "Pricing nights at a typed-in rate overrides the house's published price", "when": { "kind": "param_equals", "param": "pricing_policy", "value": "override" } } } }, "/v1/actions/hospitality.action.move_room/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_move_room` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.move_room:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_move_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allow_dirty_room": { "title": "Acknowledge moving into a dirty / pickup room", "type": "boolean" }, "new_room_id": { "format": "uuid", "title": "Room to move the guest into", "type": "string", "x-aerandil-references": "hospitality.room" }, "old_room_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Housekeeping status the vacated room lands in (default dirty)", "type": "string" }, "override_nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate for pricing_policy = override", "type": "object" }, "override_reason": { "title": "Why the override price (required with pricing_policy = override)", "type": "string" }, "pricing_policy": { "enum": [ "keep_rate", "requote", "requote_added_nights_only", "override" ], "title": "How affected nights re-price (required; never silent)", "type": "string" }, "reason": { "title": "Why the guest is moving (noise complaint, maintenance, upsell)", "type": "string" }, "reservation_room_id": { "format": "uuid", "title": "Leg being moved (required when the reservation has more than one reservation_room)", "type": "string", "x-aerandil-references": "hospitality.reservation_room" } }, "required": [ "new_room_id", "pricing_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.stay_in_room", "hospitality.link.reservation_room_assigned_to", "hospitality.link.reservation_room_for_room_type", "hospitality.link.reservation_room_charged_as_room_type" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.room", "hospitality.availability_day", "hospitality.reservation_night", "hospitality.room_discrepancy" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Move room (in-house) (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.move_room/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_move_room`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_move_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allow_dirty_room": { "title": "Acknowledge moving into a dirty / pickup room", "type": "boolean" }, "new_room_id": { "format": "uuid", "title": "Room to move the guest into", "type": "string", "x-aerandil-references": "hospitality.room" }, "old_room_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Housekeeping status the vacated room lands in (default dirty)", "type": "string" }, "override_nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate for pricing_policy = override", "type": "object" }, "override_reason": { "title": "Why the override price (required with pricing_policy = override)", "type": "string" }, "pricing_policy": { "enum": [ "keep_rate", "requote", "requote_added_nights_only", "override" ], "title": "How affected nights re-price (required; never silent)", "type": "string" }, "reason": { "title": "Why the guest is moving (noise complaint, maintenance, upsell)", "type": "string" }, "reservation_room_id": { "format": "uuid", "title": "Leg being moved (required when the reservation has more than one reservation_room)", "type": "string", "x-aerandil-references": "hospitality.reservation_room" } }, "required": [ "new_room_id", "pricing_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Move room (in-house) (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.move_room/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_move_room` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.move_room:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_move_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allow_dirty_room": { "title": "Acknowledge moving into a dirty / pickup room", "type": "boolean" }, "new_room_id": { "format": "uuid", "title": "Room to move the guest into", "type": "string", "x-aerandil-references": "hospitality.room" }, "old_room_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Housekeeping status the vacated room lands in (default dirty)", "type": "string" }, "override_nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate for pricing_policy = override", "type": "object" }, "override_reason": { "title": "Why the override price (required with pricing_policy = override)", "type": "string" }, "pricing_policy": { "enum": [ "keep_rate", "requote", "requote_added_nights_only", "override" ], "title": "How affected nights re-price (required; never silent)", "type": "string" }, "reason": { "title": "Why the guest is moving (noise complaint, maintenance, upsell)", "type": "string" }, "reservation_room_id": { "format": "uuid", "title": "Leg being moved (required when the reservation has more than one reservation_room)", "type": "string", "x-aerandil-references": "hospitality.reservation_room" } }, "required": [ "new_room_id", "pricing_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Move room (in-house) (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.offer_stay/apply": { "post": { "description": "Quote a shopper one room type on one rate plan for a stay and keep the offer — the look a regret is derived from. Priced by the admission gate `create_reservation` runs and `quote_stay` reads: refused, with the action's own refusal verbatim, when the stay could not be booked on the grid; kept with the arrival night's published rate and the stay total when it could. The first offer of a shopper's visit opens a session named by its own id; pass that `session_id` on every later offer of the visit and on the booking, which links to it. `visitor_id` is the key the house issued for the browser on an earlier visit; omitted, the house issues one — the session's id. A session that books nothing is a regret (`regret_record`), never recorded as one. A search stays the read `quote_stay` is. Holds no inventory.\n\nEffects: create hospitality.stay_offer; link hospitality.link.stay_offer_for_property; link hospitality.link.stay_offer_for_room_type; link hospitality.link.stay_offer_for_rate_plan.", "operationId": "apply_hospitality_action_offer_stay", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults": { "title": "Adults — the occupancy the grid is priced at", "type": "integer" }, "arrival_date": { "format": "date", "title": "Arrival", "type": "string" }, "departure_date": { "format": "date", "title": "Departure (the arrival date for a day-use slot)", "type": "string" }, "offered_at": { "format": "date-time", "title": "When the shopper was quoted (defaults to now; must not be in the future)", "type": "string" }, "property_id": { "format": "uuid", "title": "The house quoting", "type": "string", "x-aerandil-references": "hospitality.property" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan offered", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type offered", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "session_id": { "title": "The visit's session — its first offer's id; omit to open one", "type": "string" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "Channel the shopper came through (defaults to direct_web)", "type": "string" }, "visitor_id": { "title": "The key the house issued for this browser; omit to be issued one", "type": "string" } }, "required": [ "property_id", "room_type_id", "rate_plan_id", "arrival_date", "departure_date", "adults" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.stay_offer_for_property", "hospitality.link.stay_offer_for_room_type", "hospitality.link.stay_offer_for_rate_plan" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.stay_offer" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.offer_stay:apply" ] } ], "summary": "Offer stay", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.offer_stay/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_offer_stay` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.offer_stay:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_offer_stay", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults": { "title": "Adults — the occupancy the grid is priced at", "type": "integer" }, "arrival_date": { "format": "date", "title": "Arrival", "type": "string" }, "departure_date": { "format": "date", "title": "Departure (the arrival date for a day-use slot)", "type": "string" }, "offered_at": { "format": "date-time", "title": "When the shopper was quoted (defaults to now; must not be in the future)", "type": "string" }, "property_id": { "format": "uuid", "title": "The house quoting", "type": "string", "x-aerandil-references": "hospitality.property" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan offered", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type offered", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "session_id": { "title": "The visit's session — its first offer's id; omit to open one", "type": "string" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "Channel the shopper came through (defaults to direct_web)", "type": "string" }, "visitor_id": { "title": "The key the house issued for this browser; omit to be issued one", "type": "string" } }, "required": [ "property_id", "room_type_id", "rate_plan_id", "arrival_date", "departure_date", "adults" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.stay_offer_for_property", "hospitality.link.stay_offer_for_room_type", "hospitality.link.stay_offer_for_rate_plan" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.stay_offer" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Offer stay (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.offer_stay/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_offer_stay`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_offer_stay", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults": { "title": "Adults — the occupancy the grid is priced at", "type": "integer" }, "arrival_date": { "format": "date", "title": "Arrival", "type": "string" }, "departure_date": { "format": "date", "title": "Departure (the arrival date for a day-use slot)", "type": "string" }, "offered_at": { "format": "date-time", "title": "When the shopper was quoted (defaults to now; must not be in the future)", "type": "string" }, "property_id": { "format": "uuid", "title": "The house quoting", "type": "string", "x-aerandil-references": "hospitality.property" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan offered", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type offered", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "session_id": { "title": "The visit's session — its first offer's id; omit to open one", "type": "string" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "Channel the shopper came through (defaults to direct_web)", "type": "string" }, "visitor_id": { "title": "The key the house issued for this browser; omit to be issued one", "type": "string" } }, "required": [ "property_id", "room_type_id", "rate_plan_id", "arrival_date", "departure_date", "adults" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Offer stay (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.offer_stay/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_offer_stay` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.offer_stay:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_offer_stay", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults": { "title": "Adults — the occupancy the grid is priced at", "type": "integer" }, "arrival_date": { "format": "date", "title": "Arrival", "type": "string" }, "departure_date": { "format": "date", "title": "Departure (the arrival date for a day-use slot)", "type": "string" }, "offered_at": { "format": "date-time", "title": "When the shopper was quoted (defaults to now; must not be in the future)", "type": "string" }, "property_id": { "format": "uuid", "title": "The house quoting", "type": "string", "x-aerandil-references": "hospitality.property" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan offered", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type offered", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "session_id": { "title": "The visit's session — its first offer's id; omit to open one", "type": "string" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "Channel the shopper came through (defaults to direct_web)", "type": "string" }, "visitor_id": { "title": "The key the house issued for this browser; omit to be issued one", "type": "string" } }, "required": [ "property_id", "room_type_id", "rate_plan_id", "arrival_date", "departure_date", "adults" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Offer stay (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.offer_waitlist_entry/apply": { "post": { "description": "The desk reached the guest about a room that has freed up — OPERA's Can Move followed by the phone call — and keeps it for them: one room-night of the asked type on every ledger night of the stay goes into the ledger's `blocked` count until `offer_deadline` (the desk's own, or the property's `waitlist_offer_hold_minutes`, 30 unset). Refuses when a night of the stay has nothing left to keep. Re-offering re-stamps `offered_at` and restarts the clock but keeps the hold it has rather than taking a second room. Accept books the kept room; cancel gives it back; an offer left past its deadline lapses (`lapse_waitlist_offer`) and the room goes to the next entry. Refuses an entry that is already accepted, cancelled, or expired. At a house with `waitlist_offer_messaging` on, the offer is also sent to the guest — by SMS, or email when there is no mobile number — with a claim link, unless `notify_guest` is false.\n\nEffects: modify hospitality.waitlist_entry; modify hospitality.availability_day; create hospitality.guest_message; create hospitality.guest_conversation; modify hospitality.guest_conversation; link hospitality.link.guest_conversation_for_person; link hospitality.link.guest_conversation_at_property; link hospitality.link.guest_conversation_anchored_to_reservation; link hospitality.link.guest_message_in_conversation.", "operationId": "apply_hospitality_action_offer_waitlist_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "notes": { "title": "What was offered, and what the guest said (recorded as offer_notes)", "type": "string" }, "notify_guest": { "title": "Send the offer to the guest when the house sends waitlist offers (default true)", "type": "boolean" }, "offer_deadline": { "format": "date-time", "title": "Keep the room until (defaults to now + the property's offer clock)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.waitlist_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.guest_conversation_for_person", "hospitality.link.guest_conversation_at_property", "hospitality.link.guest_conversation_anchored_to_reservation", "hospitality.link.guest_message_in_conversation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.waitlist_entry", "hospitality.availability_day", "hospitality.guest_message", "hospitality.guest_conversation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.offer_waitlist_entry:apply" ] } ], "summary": "Offer waitlist entry", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.offer_waitlist_entry/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_offer_waitlist_entry` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.offer_waitlist_entry:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_offer_waitlist_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "notes": { "title": "What was offered, and what the guest said (recorded as offer_notes)", "type": "string" }, "notify_guest": { "title": "Send the offer to the guest when the house sends waitlist offers (default true)", "type": "boolean" }, "offer_deadline": { "format": "date-time", "title": "Keep the room until (defaults to now + the property's offer clock)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.waitlist_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.guest_conversation_for_person", "hospitality.link.guest_conversation_at_property", "hospitality.link.guest_conversation_anchored_to_reservation", "hospitality.link.guest_message_in_conversation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.waitlist_entry", "hospitality.availability_day", "hospitality.guest_message", "hospitality.guest_conversation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Offer waitlist entry (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.offer_waitlist_entry/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_offer_waitlist_entry`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_offer_waitlist_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "notes": { "title": "What was offered, and what the guest said (recorded as offer_notes)", "type": "string" }, "notify_guest": { "title": "Send the offer to the guest when the house sends waitlist offers (default true)", "type": "boolean" }, "offer_deadline": { "format": "date-time", "title": "Keep the room until (defaults to now + the property's offer clock)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.waitlist_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Offer waitlist entry (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.offer_waitlist_entry/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_offer_waitlist_entry` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.offer_waitlist_entry:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_offer_waitlist_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "notes": { "title": "What was offered, and what the guest said (recorded as offer_notes)", "type": "string" }, "notify_guest": { "title": "Send the offer to the guest when the house sends waitlist offers (default true)", "type": "boolean" }, "offer_deadline": { "format": "date-time", "title": "Keep the room until (defaults to now + the property's offer clock)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.waitlist_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Offer waitlist entry (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.onboard_staff_member/apply": { "post": { "description": "Create a `staff_member`. `employee_id` is the type's declared primary key (the property's HR / payroll identifier — or, for connector-loaded rows, the mapped vendor identity) and is unique per tenant: onboarding an employee_id that already exists replays cleanly when every parameter matches the existing row and conflicts otherwise (use `update_staff_member_profile` to change a profile). `property_id` scopes the staff member to one property; omit it for tenant-wide corporate roles. Emits `staff.onboarded`.\n\nEffects: create hospitality.staff_member.", "operationId": "apply_hospitality_action_onboard_staff_member", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "active": { "title": "Active (defaults to true)", "type": "boolean" }, "contracted_weekly_hours": { "format": "decimal", "title": "Contracted hours a week (more than 0, at most 168)", "type": "string" }, "department": { "title": "Department", "type": "string" }, "discipline": { "enum": [ "front_office", "food_beverage", "culinary", "bar", "housekeeping", "engineering", "spa", "wellness_clinical", "wellness_coaching", "sales", "revenue", "management", "other" ], "title": "Discipline (coarse ladder for pathway definitions)", "type": "string" }, "email": { "title": "Email", "type": "string" }, "employee_id": { "title": "Employee ID (the type's primary key; unique per tenant)", "type": "string" }, "family_name": { "title": "Family name", "type": "string" }, "given_name": { "title": "Given name", "type": "string" }, "most_recent_hire_date": { "format": "date", "title": "Most recent hire date", "type": "string" }, "property_id": { "format": "uuid", "title": "Property to scope the staff member at (omit for tenant-wide roles)", "type": "string", "x-aerandil-references": "hospitality.property" }, "role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "Role", "type": "string" } }, "required": [ "employee_id", "given_name", "family_name", "role" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.staff_member" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.onboard_staff_member:apply" ] } ], "summary": "Onboard staff member", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.onboard_staff_member/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_onboard_staff_member` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.onboard_staff_member:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_onboard_staff_member", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "active": { "title": "Active (defaults to true)", "type": "boolean" }, "contracted_weekly_hours": { "format": "decimal", "title": "Contracted hours a week (more than 0, at most 168)", "type": "string" }, "department": { "title": "Department", "type": "string" }, "discipline": { "enum": [ "front_office", "food_beverage", "culinary", "bar", "housekeeping", "engineering", "spa", "wellness_clinical", "wellness_coaching", "sales", "revenue", "management", "other" ], "title": "Discipline (coarse ladder for pathway definitions)", "type": "string" }, "email": { "title": "Email", "type": "string" }, "employee_id": { "title": "Employee ID (the type's primary key; unique per tenant)", "type": "string" }, "family_name": { "title": "Family name", "type": "string" }, "given_name": { "title": "Given name", "type": "string" }, "most_recent_hire_date": { "format": "date", "title": "Most recent hire date", "type": "string" }, "property_id": { "format": "uuid", "title": "Property to scope the staff member at (omit for tenant-wide roles)", "type": "string", "x-aerandil-references": "hospitality.property" }, "role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "Role", "type": "string" } }, "required": [ "employee_id", "given_name", "family_name", "role" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.staff_member" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Onboard staff member (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.onboard_staff_member/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_onboard_staff_member`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_onboard_staff_member", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "active": { "title": "Active (defaults to true)", "type": "boolean" }, "contracted_weekly_hours": { "format": "decimal", "title": "Contracted hours a week (more than 0, at most 168)", "type": "string" }, "department": { "title": "Department", "type": "string" }, "discipline": { "enum": [ "front_office", "food_beverage", "culinary", "bar", "housekeeping", "engineering", "spa", "wellness_clinical", "wellness_coaching", "sales", "revenue", "management", "other" ], "title": "Discipline (coarse ladder for pathway definitions)", "type": "string" }, "email": { "title": "Email", "type": "string" }, "employee_id": { "title": "Employee ID (the type's primary key; unique per tenant)", "type": "string" }, "family_name": { "title": "Family name", "type": "string" }, "given_name": { "title": "Given name", "type": "string" }, "most_recent_hire_date": { "format": "date", "title": "Most recent hire date", "type": "string" }, "property_id": { "format": "uuid", "title": "Property to scope the staff member at (omit for tenant-wide roles)", "type": "string", "x-aerandil-references": "hospitality.property" }, "role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "Role", "type": "string" } }, "required": [ "employee_id", "given_name", "family_name", "role" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Onboard staff member (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.onboard_staff_member/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_onboard_staff_member` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.onboard_staff_member:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_onboard_staff_member", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "active": { "title": "Active (defaults to true)", "type": "boolean" }, "contracted_weekly_hours": { "format": "decimal", "title": "Contracted hours a week (more than 0, at most 168)", "type": "string" }, "department": { "title": "Department", "type": "string" }, "discipline": { "enum": [ "front_office", "food_beverage", "culinary", "bar", "housekeeping", "engineering", "spa", "wellness_clinical", "wellness_coaching", "sales", "revenue", "management", "other" ], "title": "Discipline (coarse ladder for pathway definitions)", "type": "string" }, "email": { "title": "Email", "type": "string" }, "employee_id": { "title": "Employee ID (the type's primary key; unique per tenant)", "type": "string" }, "family_name": { "title": "Family name", "type": "string" }, "given_name": { "title": "Given name", "type": "string" }, "most_recent_hire_date": { "format": "date", "title": "Most recent hire date", "type": "string" }, "property_id": { "format": "uuid", "title": "Property to scope the staff member at (omit for tenant-wide roles)", "type": "string", "x-aerandil-references": "hospitality.property" }, "role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "Role", "type": "string" } }, "required": [ "employee_id", "given_name", "family_name", "role" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Onboard staff member (rollup delta)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.open_agent_thread/apply": { "post": { "description": "Open a persistent operator↔agent conversation thread (agent-stack design D9: threads live server-side in the ontology, so the Explorer panel, the runtime, and any future surface stay stateless). Tenant-scoped, no anchor. Emits `agent_thread.opened`.\n\nEffects: create hospitality.agent_thread.", "operationId": "apply_hospitality_action_open_agent_thread", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "agent_key": { "title": "The agent definition this thread converses with", "type": "string" }, "subject": { "title": "Display subject (defaults to the opening task's first line)", "type": "string" } }, "required": [ "agent_key" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.agent_thread" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.open_agent_thread:apply" ] } ], "summary": "Open agent thread", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.open_agent_thread/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_open_agent_thread` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.open_agent_thread:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_open_agent_thread", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "agent_key": { "title": "The agent definition this thread converses with", "type": "string" }, "subject": { "title": "Display subject (defaults to the opening task's first line)", "type": "string" } }, "required": [ "agent_key" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.agent_thread" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Open agent thread (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.open_agent_thread/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_open_agent_thread`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_open_agent_thread", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "agent_key": { "title": "The agent definition this thread converses with", "type": "string" }, "subject": { "title": "Display subject (defaults to the opening task's first line)", "type": "string" } }, "required": [ "agent_key" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Open agent thread (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.open_agent_thread/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_open_agent_thread` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.open_agent_thread:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_open_agent_thread", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "agent_key": { "title": "The agent definition this thread converses with", "type": "string" }, "subject": { "title": "Display subject (defaults to the opening task's first line)", "type": "string" } }, "required": [ "agent_key" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Open agent thread (rollup delta)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.open_approval_gate/apply": { "post": { "description": "Record the first in-product open/view of a live gate — the approver-side view-tracking half of the §4.4.1 lifecycle. Stamps `opened_at` once, advances a requested / assigned / notified gate to `opened` (a partially-approved gate keeps its status), and emits `approval_gate.opened` on that first open only. Re-opens are no-ops — the spec tracks the first view, not every view.\n\nEffects: modify hospitality.approval_gate.", "operationId": "apply_hospitality_action_open_approval_gate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.approval_gate" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.approval_gate" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.open_approval_gate:apply" ] } ], "summary": "Open approval gate", "tags": [ "approvals" ] } }, "/v1/actions/hospitality.action.open_approval_gate/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_open_approval_gate` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.open_approval_gate:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_open_approval_gate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.approval_gate" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.approval_gate" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Open approval gate (dry-run)", "tags": [ "approvals" ] } }, "/v1/actions/hospitality.action.open_approval_gate/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_open_approval_gate`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_open_approval_gate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.approval_gate" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Open approval gate (dry-run)", "tags": [ "approvals" ] } }, "/v1/actions/hospitality.action.open_approval_gate/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_open_approval_gate` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.open_approval_gate:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_open_approval_gate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.approval_gate" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Open approval gate (rollup delta)", "tags": [ "approvals" ] } }, "/v1/actions/hospitality.action.open_business_date/apply": { "post": { "description": "Open the property's accounting day: mints the BusinessDate row (status open) that charges, postings, and restrictions attach to. Exactly one business date may be open per property; the previous one must close through run_night_audit first. Idempotence: re-opening the same date is refused with a clear error rather than minting a duplicate day. Normally only needed once — run_night_audit rolls the next day open as it closes the last. The property carries the open day (open_business_date, business_date_opened_at): the hotel date every posting made from now is dated to, so a charge at 01:30 before the close lands on the day still open.\n\nEffects: create hospitality.business_date; modify hospitality.property.", "operationId": "apply_hospitality_action_open_business_date", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" } }, "required": [ "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.business_date", "hospitality.property" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.open_business_date:apply" ] } ], "summary": "Open business date", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.open_business_date/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_open_business_date` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.open_business_date:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_open_business_date", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" } }, "required": [ "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.business_date", "hospitality.property" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Open business date (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.open_business_date/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_open_business_date`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_open_business_date", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" } }, "required": [ "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Open business date (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.open_business_date/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_open_business_date` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.open_business_date:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_open_business_date", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" } }, "required": [ "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Open business date (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.open_cashier_session/apply": { "post": { "description": "Open a cash shift against an active cashier with a starting float (zero is legal — a short drawer at close is a variance, never a negative float). One open session per cashier per currency: a multi-currency desk opens one session per currency, decomposing Mews's per-currency balances. The session's currency is the float's; every movement in the shift must match it. Business-time opened_at defaults to now.\n\nEffects: create hospitality.cashier_session; link hospitality.link.cashier_session_for_cashier.", "operationId": "apply_hospitality_action_open_cashier_session", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cashier_id": { "format": "uuid", "title": "The till to open against", "type": "string", "x-aerandil-references": "hospitality.cashier" }, "notes": { "title": "Notes", "type": "string" }, "opened_at": { "format": "date-time", "title": "Shift start (business time; defaults to now)", "type": "string" }, "opening_float": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Starting float", "type": "object" } }, "required": [ "cashier_id", "opening_float" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.cashier_session_for_cashier" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.cashier_session" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.open_cashier_session:apply" ] } ], "summary": "Open cashier session", "tags": [ "cashiering" ] } }, "/v1/actions/hospitality.action.open_cashier_session/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_open_cashier_session` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.open_cashier_session:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_open_cashier_session", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cashier_id": { "format": "uuid", "title": "The till to open against", "type": "string", "x-aerandil-references": "hospitality.cashier" }, "notes": { "title": "Notes", "type": "string" }, "opened_at": { "format": "date-time", "title": "Shift start (business time; defaults to now)", "type": "string" }, "opening_float": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Starting float", "type": "object" } }, "required": [ "cashier_id", "opening_float" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.cashier_session_for_cashier" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.cashier_session" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Open cashier session (dry-run)", "tags": [ "cashiering" ] } }, "/v1/actions/hospitality.action.open_cashier_session/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_open_cashier_session`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_open_cashier_session", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cashier_id": { "format": "uuid", "title": "The till to open against", "type": "string", "x-aerandil-references": "hospitality.cashier" }, "notes": { "title": "Notes", "type": "string" }, "opened_at": { "format": "date-time", "title": "Shift start (business time; defaults to now)", "type": "string" }, "opening_float": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Starting float", "type": "object" } }, "required": [ "cashier_id", "opening_float" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Open cashier session (dry-run)", "tags": [ "cashiering" ] } }, "/v1/actions/hospitality.action.open_cashier_session/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_open_cashier_session` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.open_cashier_session:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_open_cashier_session", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cashier_id": { "format": "uuid", "title": "The till to open against", "type": "string", "x-aerandil-references": "hospitality.cashier" }, "notes": { "title": "Notes", "type": "string" }, "opened_at": { "format": "date-time", "title": "Shift start (business time; defaults to now)", "type": "string" }, "opening_float": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Starting float", "type": "object" } }, "required": [ "cashier_id", "opening_float" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Open cashier session (rollup delta)", "tags": [ "cashiering" ] } }, "/v1/actions/hospitality.action.open_channel_connection/apply": { "post": { "description": "Register a conduit between a property and a distribution partner. Created `pending_mapping`: a conduit with no `channel_mapping` rows can publish nothing, and publishing or accepting an unmapped code is a named failure in both the SiteMinder and Mews certification suites — so the birth state says so rather than letting an empty conduit look healthy. `channel_ids` names the demand channels the conduit carries; a channel manager fronts many, and each keeps its own commission period. `secret_ref` names a credential in the external secret store — never pass the credential itself. `rate_model` and `price_basis` are fixed per conduit, not per property: SiteMinder configures the pricing model at integration level and will not let properties differ. Emits `channel_connection.opened`.\n\nEffects: create hospitality.channel_connection; link hospitality.link.channel_connection_for_property; link hospitality.link.channel_connection_carries_channel.", "operationId": "apply_hospitality_action_open_channel_connection", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "ari_endpoint_url": { "title": "HTTPS endpoint we publish ARI into", "type": "string" }, "channel_ids": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.channel" }, "title": "Demand channels this conduit carries", "type": "array" }, "display_name": { "title": "Human-readable name shown in the Explorer", "type": "string" }, "horizon_days": { "title": "Days forward from today that ARI is published for (1..=750)", "type": "integer" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "owner_client_ref": { "title": "Client registering this subscription (subscription provisioning only)", "type": "string" }, "partner_code": { "title": "The partner's identifier for our system (SiteMinder RequestorID / pmsCode)", "type": "string" }, "price_basis": { "enum": [ "gross", "net", "gross_and_net" ], "title": "Whether published amounts are gross, net, or both (default gross_and_net)", "type": "string" }, "property_code": { "title": "The partner's identifier for this property (SiteMinder HotelCode)", "type": "string" }, "protocol": { "enum": [ "pmsx_ota_2003_05", "mews_chm_v1", "aerandil_ari_v1", "other" ], "title": "Wire dialect this conduit speaks", "type": "string" }, "provider": { "title": "Partner identifier (siteminder / d_edge / derbysoft / …)", "type": "string" }, "provisioning": { "enum": [ "partner_hosted", "subscription" ], "title": "Who stood the conduit up (we call them, or they subscribed to us)", "type": "string" }, "rate_model": { "enum": [ "per_day", "occupancy_based" ], "title": "Published rate model — fixed per conduit, never per property", "type": "string" }, "reservation_delivery": { "enum": [ "partner_push", "we_pull", "none" ], "title": "How reservations reach us from the partner", "type": "string" }, "secret_ref": { "title": "Name of the credential in the external secret store (never the value)", "type": "string" } }, "required": [ "display_name", "provider", "protocol", "provisioning", "rate_model", "reservation_delivery", "horizon_days" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.channel_connection_for_property", "hospitality.link.channel_connection_carries_channel" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.channel_connection" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.open_channel_connection:apply" ] } ], "summary": "Open channel connection", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.open_channel_connection/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_open_channel_connection` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.open_channel_connection:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_open_channel_connection", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "ari_endpoint_url": { "title": "HTTPS endpoint we publish ARI into", "type": "string" }, "channel_ids": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.channel" }, "title": "Demand channels this conduit carries", "type": "array" }, "display_name": { "title": "Human-readable name shown in the Explorer", "type": "string" }, "horizon_days": { "title": "Days forward from today that ARI is published for (1..=750)", "type": "integer" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "owner_client_ref": { "title": "Client registering this subscription (subscription provisioning only)", "type": "string" }, "partner_code": { "title": "The partner's identifier for our system (SiteMinder RequestorID / pmsCode)", "type": "string" }, "price_basis": { "enum": [ "gross", "net", "gross_and_net" ], "title": "Whether published amounts are gross, net, or both (default gross_and_net)", "type": "string" }, "property_code": { "title": "The partner's identifier for this property (SiteMinder HotelCode)", "type": "string" }, "protocol": { "enum": [ "pmsx_ota_2003_05", "mews_chm_v1", "aerandil_ari_v1", "other" ], "title": "Wire dialect this conduit speaks", "type": "string" }, "provider": { "title": "Partner identifier (siteminder / d_edge / derbysoft / …)", "type": "string" }, "provisioning": { "enum": [ "partner_hosted", "subscription" ], "title": "Who stood the conduit up (we call them, or they subscribed to us)", "type": "string" }, "rate_model": { "enum": [ "per_day", "occupancy_based" ], "title": "Published rate model — fixed per conduit, never per property", "type": "string" }, "reservation_delivery": { "enum": [ "partner_push", "we_pull", "none" ], "title": "How reservations reach us from the partner", "type": "string" }, "secret_ref": { "title": "Name of the credential in the external secret store (never the value)", "type": "string" } }, "required": [ "display_name", "provider", "protocol", "provisioning", "rate_model", "reservation_delivery", "horizon_days" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.channel_connection_for_property", "hospitality.link.channel_connection_carries_channel" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.channel_connection" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Open channel connection (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.open_channel_connection/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_open_channel_connection`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_open_channel_connection", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "ari_endpoint_url": { "title": "HTTPS endpoint we publish ARI into", "type": "string" }, "channel_ids": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.channel" }, "title": "Demand channels this conduit carries", "type": "array" }, "display_name": { "title": "Human-readable name shown in the Explorer", "type": "string" }, "horizon_days": { "title": "Days forward from today that ARI is published for (1..=750)", "type": "integer" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "owner_client_ref": { "title": "Client registering this subscription (subscription provisioning only)", "type": "string" }, "partner_code": { "title": "The partner's identifier for our system (SiteMinder RequestorID / pmsCode)", "type": "string" }, "price_basis": { "enum": [ "gross", "net", "gross_and_net" ], "title": "Whether published amounts are gross, net, or both (default gross_and_net)", "type": "string" }, "property_code": { "title": "The partner's identifier for this property (SiteMinder HotelCode)", "type": "string" }, "protocol": { "enum": [ "pmsx_ota_2003_05", "mews_chm_v1", "aerandil_ari_v1", "other" ], "title": "Wire dialect this conduit speaks", "type": "string" }, "provider": { "title": "Partner identifier (siteminder / d_edge / derbysoft / …)", "type": "string" }, "provisioning": { "enum": [ "partner_hosted", "subscription" ], "title": "Who stood the conduit up (we call them, or they subscribed to us)", "type": "string" }, "rate_model": { "enum": [ "per_day", "occupancy_based" ], "title": "Published rate model — fixed per conduit, never per property", "type": "string" }, "reservation_delivery": { "enum": [ "partner_push", "we_pull", "none" ], "title": "How reservations reach us from the partner", "type": "string" }, "secret_ref": { "title": "Name of the credential in the external secret store (never the value)", "type": "string" } }, "required": [ "display_name", "provider", "protocol", "provisioning", "rate_model", "reservation_delivery", "horizon_days" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Open channel connection (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.open_channel_connection/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_open_channel_connection` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.open_channel_connection:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_open_channel_connection", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "ari_endpoint_url": { "title": "HTTPS endpoint we publish ARI into", "type": "string" }, "channel_ids": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.channel" }, "title": "Demand channels this conduit carries", "type": "array" }, "display_name": { "title": "Human-readable name shown in the Explorer", "type": "string" }, "horizon_days": { "title": "Days forward from today that ARI is published for (1..=750)", "type": "integer" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "owner_client_ref": { "title": "Client registering this subscription (subscription provisioning only)", "type": "string" }, "partner_code": { "title": "The partner's identifier for our system (SiteMinder RequestorID / pmsCode)", "type": "string" }, "price_basis": { "enum": [ "gross", "net", "gross_and_net" ], "title": "Whether published amounts are gross, net, or both (default gross_and_net)", "type": "string" }, "property_code": { "title": "The partner's identifier for this property (SiteMinder HotelCode)", "type": "string" }, "protocol": { "enum": [ "pmsx_ota_2003_05", "mews_chm_v1", "aerandil_ari_v1", "other" ], "title": "Wire dialect this conduit speaks", "type": "string" }, "provider": { "title": "Partner identifier (siteminder / d_edge / derbysoft / …)", "type": "string" }, "provisioning": { "enum": [ "partner_hosted", "subscription" ], "title": "Who stood the conduit up (we call them, or they subscribed to us)", "type": "string" }, "rate_model": { "enum": [ "per_day", "occupancy_based" ], "title": "Published rate model — fixed per conduit, never per property", "type": "string" }, "reservation_delivery": { "enum": [ "partner_push", "we_pull", "none" ], "title": "How reservations reach us from the partner", "type": "string" }, "secret_ref": { "title": "Name of the credential in the external secret store (never the value)", "type": "string" } }, "required": [ "display_name", "provider", "protocol", "provisioning", "rate_model", "reservation_delivery", "horizon_days" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Open channel connection (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.open_check/apply": { "post": { "description": "Open a guest check against an outlet — and, for dine-in, seat a table: the table must be available or reserved and flips to seated. Takeaway / room-service / delivery checks carry no table. Business time: `opened_at` is when service actually opened the check (defaults to now for live POS use); replayed histories pass it explicitly so the check lands on the business day it happened. The check records its `business_date` — the property's hotel date at `opened_at` — and the meal period it rings in (`daypart`), which every line's price and VAT resolve on and a package's meal allowance matches. Absent on a live check, `daypart` is the outlet's period in force on the house's wall clock (`set_outlet_meal_periods`; none in a gap or with no hours set); a replay naming `opened_at` keeps what it says. Its totals start at zero in the property's default currency. A present `external_ref` routes the create through the `guest_check_external_ref` business key, making a crashed-pass retry a replay instead of a duplicate check. In-room dining: a `room_service` check names the in-house `stay_id` at the outlet's house it goes up to (required) and is linked to it (`check_for_stay`), snapshotting the stay's `room`, and starts its dispatch sheet — `delivery_status` `taken`, `promised_at` as quoted, else twenty minutes after opening for a breakfast and thirty for any other meal. Any other kind may name an in-house stay too (the roster's guest seated in the restaurant): it is linked and its room snapshotted, with no dispatch sheet; only room service quotes a `promised_at`. Emits `fnb.check_opened`.\n\nEffects: create hospitality.guest_check; link hospitality.link.check_for_stay; link hospitality.link.check_at_outlet; link hospitality.link.check_opened_at_table; modify hospitality.service_table.", "operationId": "apply_hospitality_action_open_check", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "covers": { "title": "Covers seated", "type": "integer" }, "daypart": { "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "title": "Meal period the check rings in (the daypart a price row may be narrowed to)", "type": "string" }, "external_ref": { "title": "Source-system key for replayed / connector-landed checks (replay key)", "type": "string" }, "opened_at": { "format": "date-time", "title": "When the check opened — business time, not record time (defaults to now)", "type": "string" }, "order_kind": { "enum": [ "dine_in", "takeaway", "room_service", "delivery" ], "title": "How the order reaches the guest", "type": "string" }, "outlet_id": { "format": "uuid", "title": "Outlet the check trades under", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "promised_at": { "format": "date-time", "title": "When the in-room order is promised at the room (room_service only)", "type": "string" }, "server_id": { "format": "uuid", "title": "Owning server", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "stay_id": { "format": "uuid", "title": "In-house stay the check is for (required on room_service, optional otherwise)", "type": "string", "x-aerandil-references": "hospitality.stay" }, "table_id": { "format": "uuid", "title": "Table to seat (dine-in only)", "type": "string", "x-aerandil-references": "hospitality.service_table" } }, "required": [ "outlet_id", "order_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.check_for_stay", "hospitality.link.check_at_outlet", "hospitality.link.check_opened_at_table" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.guest_check", "hospitality.service_table" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.open_check:apply" ] } ], "summary": "Open check", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.open_check/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_open_check` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.open_check:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_open_check", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "covers": { "title": "Covers seated", "type": "integer" }, "daypart": { "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "title": "Meal period the check rings in (the daypart a price row may be narrowed to)", "type": "string" }, "external_ref": { "title": "Source-system key for replayed / connector-landed checks (replay key)", "type": "string" }, "opened_at": { "format": "date-time", "title": "When the check opened — business time, not record time (defaults to now)", "type": "string" }, "order_kind": { "enum": [ "dine_in", "takeaway", "room_service", "delivery" ], "title": "How the order reaches the guest", "type": "string" }, "outlet_id": { "format": "uuid", "title": "Outlet the check trades under", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "promised_at": { "format": "date-time", "title": "When the in-room order is promised at the room (room_service only)", "type": "string" }, "server_id": { "format": "uuid", "title": "Owning server", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "stay_id": { "format": "uuid", "title": "In-house stay the check is for (required on room_service, optional otherwise)", "type": "string", "x-aerandil-references": "hospitality.stay" }, "table_id": { "format": "uuid", "title": "Table to seat (dine-in only)", "type": "string", "x-aerandil-references": "hospitality.service_table" } }, "required": [ "outlet_id", "order_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.check_for_stay", "hospitality.link.check_at_outlet", "hospitality.link.check_opened_at_table" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.guest_check", "hospitality.service_table" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Open check (dry-run)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.open_check/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_open_check`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_open_check", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "covers": { "title": "Covers seated", "type": "integer" }, "daypart": { "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "title": "Meal period the check rings in (the daypart a price row may be narrowed to)", "type": "string" }, "external_ref": { "title": "Source-system key for replayed / connector-landed checks (replay key)", "type": "string" }, "opened_at": { "format": "date-time", "title": "When the check opened — business time, not record time (defaults to now)", "type": "string" }, "order_kind": { "enum": [ "dine_in", "takeaway", "room_service", "delivery" ], "title": "How the order reaches the guest", "type": "string" }, "outlet_id": { "format": "uuid", "title": "Outlet the check trades under", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "promised_at": { "format": "date-time", "title": "When the in-room order is promised at the room (room_service only)", "type": "string" }, "server_id": { "format": "uuid", "title": "Owning server", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "stay_id": { "format": "uuid", "title": "In-house stay the check is for (required on room_service, optional otherwise)", "type": "string", "x-aerandil-references": "hospitality.stay" }, "table_id": { "format": "uuid", "title": "Table to seat (dine-in only)", "type": "string", "x-aerandil-references": "hospitality.service_table" } }, "required": [ "outlet_id", "order_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Open check (dry-run)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.open_check/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_open_check` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.open_check:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_open_check", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "covers": { "title": "Covers seated", "type": "integer" }, "daypart": { "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "title": "Meal period the check rings in (the daypart a price row may be narrowed to)", "type": "string" }, "external_ref": { "title": "Source-system key for replayed / connector-landed checks (replay key)", "type": "string" }, "opened_at": { "format": "date-time", "title": "When the check opened — business time, not record time (defaults to now)", "type": "string" }, "order_kind": { "enum": [ "dine_in", "takeaway", "room_service", "delivery" ], "title": "How the order reaches the guest", "type": "string" }, "outlet_id": { "format": "uuid", "title": "Outlet the check trades under", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "promised_at": { "format": "date-time", "title": "When the in-room order is promised at the room (room_service only)", "type": "string" }, "server_id": { "format": "uuid", "title": "Owning server", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "stay_id": { "format": "uuid", "title": "In-house stay the check is for (required on room_service, optional otherwise)", "type": "string", "x-aerandil-references": "hospitality.stay" }, "table_id": { "format": "uuid", "title": "Table to seat (dine-in only)", "type": "string", "x-aerandil-references": "hospitality.service_table" } }, "required": [ "outlet_id", "order_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Open check (rollup delta)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.open_company_ar_folio/apply": { "post": { "description": "Open the company's A/R account at a property — a `company_ar` folio opened at zero in the given currency, linked through `company_has_ar_folio`. The desk direct-bills a guest folio by taking a `direct_billing` payment on it and posting the receivable here; `settle_folio_to_ar` records the transfer and its due date. A company that already has an open account at the property in that currency is a no-op. Emits `company.ar_folio_opened`.\n\nEffects: create hospitality.folio; link hospitality.link.company_has_ar_folio.", "operationId": "apply_hospitality_action_open_company_ar_folio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "currency": { "format": "iso-4217", "title": "Folio currency (ISO 4217)", "type": "string" }, "property_id": { "format": "uuid", "title": "The property the account is held at", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "property_id", "currency" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.company" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.company_has_ar_folio" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.open_company_ar_folio:apply" ] } ], "summary": "Open company A/R folio", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.open_company_ar_folio/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_open_company_ar_folio` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.open_company_ar_folio:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_open_company_ar_folio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "currency": { "format": "iso-4217", "title": "Folio currency (ISO 4217)", "type": "string" }, "property_id": { "format": "uuid", "title": "The property the account is held at", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "property_id", "currency" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.company" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.company_has_ar_folio" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Open company A/R folio (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.open_company_ar_folio/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_open_company_ar_folio`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_open_company_ar_folio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "currency": { "format": "iso-4217", "title": "Folio currency (ISO 4217)", "type": "string" }, "property_id": { "format": "uuid", "title": "The property the account is held at", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "property_id", "currency" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.company" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Open company A/R folio (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.open_company_ar_folio/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_open_company_ar_folio` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.open_company_ar_folio:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_open_company_ar_folio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "currency": { "format": "iso-4217", "title": "Folio currency (ISO 4217)", "type": "string" }, "property_id": { "format": "uuid", "title": "The property the account is held at", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "property_id", "currency" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.company" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Open company A/R folio (rollup delta)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.open_group_master_folio/apply": { "post": { "description": "Open the block's master folio — a `group_master` folio at the property, opened at zero in the given currency, linked through `block_has_master_folio`. Pickups' folios join it by binding a routing rule whose target is this folio (`bind_folio_routing_rule`), after which charges that rule takes post here instead of on the guest's bill. Refused on a cancelled block; a block that already has a master is a no-op. Emits `group_block.master_folio_opened`.\n\nEffects: create hospitality.folio; link hospitality.link.block_has_master_folio.", "operationId": "apply_hospitality_action_open_group_master_folio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "currency": { "format": "iso-4217", "title": "Folio currency (ISO 4217)", "type": "string" } }, "required": [ "currency" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_block" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.block_has_master_folio" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.open_group_master_folio:apply" ] } ], "summary": "Open group master folio", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.open_group_master_folio/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_open_group_master_folio` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.open_group_master_folio:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_open_group_master_folio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "currency": { "format": "iso-4217", "title": "Folio currency (ISO 4217)", "type": "string" } }, "required": [ "currency" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_block" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.block_has_master_folio" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Open group master folio (dry-run)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.open_group_master_folio/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_open_group_master_folio`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_open_group_master_folio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "currency": { "format": "iso-4217", "title": "Folio currency (ISO 4217)", "type": "string" } }, "required": [ "currency" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_block" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Open group master folio (dry-run)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.open_group_master_folio/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_open_group_master_folio` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.open_group_master_folio:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_open_group_master_folio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "currency": { "format": "iso-4217", "title": "Folio currency (ISO 4217)", "type": "string" } }, "required": [ "currency" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_block" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Open group master folio (rollup delta)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.open_pattern_detection_run/apply": { "post": { "description": "Open a property-scoped recovery_pattern_detection_run for a scan window and signal set. The run remains in_progress until close_pattern_detection_run marks it completed or failed.\n\nEffects: create hospitality.recovery_pattern_detection_run; link hospitality.link.recovery_pattern_run_for_property.", "operationId": "apply_hospitality_action_open_pattern_detection_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cadence": { "enum": [ "nightly", "weekly", "monthly", "event_triggered", "manual" ], "title": "Run cadence", "type": "string" }, "scan_method": { "title": "Detector method or rule-set description", "type": "string" }, "scan_signals": { "items": { "enum": [ "service_recovery_event", "pre_shift_lineup_event", "message_triage", "work_order", "housekeeping_task", "recognition_event", "review_aggregate" ], "type": "string" }, "title": "Signals included in the scan", "type": "array" }, "scan_window_end": { "format": "date-time", "title": "Scan window end", "type": "string" }, "scan_window_start": { "format": "date-time", "title": "Scan window start", "type": "string" } }, "required": [ "cadence", "scan_window_start", "scan_window_end", "scan_signals", "scan_method" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.recovery_pattern_run_for_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.recovery_pattern_detection_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.open_pattern_detection_run:apply" ] } ], "summary": "Open pattern detection run", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.open_pattern_detection_run/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_open_pattern_detection_run` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.open_pattern_detection_run:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_open_pattern_detection_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cadence": { "enum": [ "nightly", "weekly", "monthly", "event_triggered", "manual" ], "title": "Run cadence", "type": "string" }, "scan_method": { "title": "Detector method or rule-set description", "type": "string" }, "scan_signals": { "items": { "enum": [ "service_recovery_event", "pre_shift_lineup_event", "message_triage", "work_order", "housekeeping_task", "recognition_event", "review_aggregate" ], "type": "string" }, "title": "Signals included in the scan", "type": "array" }, "scan_window_end": { "format": "date-time", "title": "Scan window end", "type": "string" }, "scan_window_start": { "format": "date-time", "title": "Scan window start", "type": "string" } }, "required": [ "cadence", "scan_window_start", "scan_window_end", "scan_signals", "scan_method" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.recovery_pattern_run_for_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.recovery_pattern_detection_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Open pattern detection run (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.open_pattern_detection_run/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_open_pattern_detection_run`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_open_pattern_detection_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cadence": { "enum": [ "nightly", "weekly", "monthly", "event_triggered", "manual" ], "title": "Run cadence", "type": "string" }, "scan_method": { "title": "Detector method or rule-set description", "type": "string" }, "scan_signals": { "items": { "enum": [ "service_recovery_event", "pre_shift_lineup_event", "message_triage", "work_order", "housekeeping_task", "recognition_event", "review_aggregate" ], "type": "string" }, "title": "Signals included in the scan", "type": "array" }, "scan_window_end": { "format": "date-time", "title": "Scan window end", "type": "string" }, "scan_window_start": { "format": "date-time", "title": "Scan window start", "type": "string" } }, "required": [ "cadence", "scan_window_start", "scan_window_end", "scan_signals", "scan_method" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Open pattern detection run (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.open_pattern_detection_run/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_open_pattern_detection_run` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.open_pattern_detection_run:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_open_pattern_detection_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cadence": { "enum": [ "nightly", "weekly", "monthly", "event_triggered", "manual" ], "title": "Run cadence", "type": "string" }, "scan_method": { "title": "Detector method or rule-set description", "type": "string" }, "scan_signals": { "items": { "enum": [ "service_recovery_event", "pre_shift_lineup_event", "message_triage", "work_order", "housekeeping_task", "recognition_event", "review_aggregate" ], "type": "string" }, "title": "Signals included in the scan", "type": "array" }, "scan_window_end": { "format": "date-time", "title": "Scan window end", "type": "string" }, "scan_window_start": { "format": "date-time", "title": "Scan window start", "type": "string" } }, "required": [ "cadence", "scan_window_start", "scan_window_end", "scan_signals", "scan_method" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Open pattern detection run (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.open_rebate_folio/apply": { "post": { "description": "Open a rebate folio against a sealed bill — the correction path for a folio closed beyond the reopen window, where `reopen_folio` refuses by design. The original is never touched: `reverse_charge` and `refund_payment` route their sealed-folio legs onto the rebate folio, late charges post to it directly, and it settles and closes through the ordinary machinery (`apply_payment`, `settle_folio_to_ar`, `close_folio`). Refuses an open folio (correct it directly), a void folio, and a folio still provably inside the reopen window (`reopen_folio` is that path — one clock per case, no overlap). Re-applying while a rebate folio is already open is a no-op: corrective lines must have exactly one place to land.\n\nEffects: create hospitality.folio; link hospitality.link.folio_rebates_folio.", "operationId": "apply_hospitality_action_open_rebate_folio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "note": { "title": "Free-text context for the correction; the corrective lines carry their own reason taxonomies", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_rebates_folio" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.open_rebate_folio:apply" ] } ], "summary": "Open rebate folio", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.open_rebate_folio/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_open_rebate_folio` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.open_rebate_folio:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_open_rebate_folio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "note": { "title": "Free-text context for the correction; the corrective lines carry their own reason taxonomies", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_rebates_folio" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Open rebate folio (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.open_rebate_folio/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_open_rebate_folio`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_open_rebate_folio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "note": { "title": "Free-text context for the correction; the corrective lines carry their own reason taxonomies", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Open rebate folio (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.open_rebate_folio/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_open_rebate_folio` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.open_rebate_folio:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_open_rebate_folio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "note": { "title": "Free-text context for the correction; the corrective lines carry their own reason taxonomies", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Open rebate folio (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.open_staff_employment_period/apply": { "post": { "description": "Open a new employment period for a staff member; auto- closes the prior open period if present. Updates `staff_member.most_recent_hire_date`.\n\nEffects: create hospitality.staff_employment_period; modify hospitality.staff_employment_period; modify hospitality.staff_member; link hospitality.link.staff_employment_period_for_staff.", "operationId": "apply_hospitality_action_open_staff_employment_period", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "hire_date": { "format": "date", "title": "Hire date", "type": "string" }, "role_at_hire": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "Role at hire", "type": "string" } }, "required": [ "hire_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.staff_employment_period_for_staff" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.staff_employment_period", "hospitality.staff_member" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.open_staff_employment_period:apply" ] } ], "summary": "Open staff employment period", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.open_staff_employment_period/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_open_staff_employment_period` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.open_staff_employment_period:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_open_staff_employment_period", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "hire_date": { "format": "date", "title": "Hire date", "type": "string" }, "role_at_hire": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "Role at hire", "type": "string" } }, "required": [ "hire_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.staff_employment_period_for_staff" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.staff_employment_period", "hospitality.staff_member" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Open staff employment period (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.open_staff_employment_period/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_open_staff_employment_period`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_open_staff_employment_period", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "hire_date": { "format": "date", "title": "Hire date", "type": "string" }, "role_at_hire": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "Role at hire", "type": "string" } }, "required": [ "hire_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Open staff employment period (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.open_staff_employment_period/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_open_staff_employment_period` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.open_staff_employment_period:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_open_staff_employment_period", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "hire_date": { "format": "date", "title": "Hire date", "type": "string" }, "role_at_hire": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "Role at hire", "type": "string" } }, "required": [ "hire_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Open staff employment period (rollup delta)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.pause_automation/apply": { "post": { "description": "Pause an `active` automation — the evaluator stops firing it, reversibly. `reason` lands on the audit event. Idempotent on an already-paused automation; refused on an `archived` one. Emits `automation.paused`.\n\nEffects: modify hospitality.automation.", "operationId": "apply_hospitality_action_pause_automation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the automation is being paused", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.automation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.automation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.pause_automation:apply" ] } ], "summary": "Pause automation", "tags": [ "automation" ] } }, "/v1/actions/hospitality.action.pause_automation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_pause_automation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.pause_automation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_pause_automation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the automation is being paused", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.automation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.automation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Pause automation (dry-run)", "tags": [ "automation" ] } }, "/v1/actions/hospitality.action.pause_automation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_pause_automation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_pause_automation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the automation is being paused", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.automation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Pause automation (dry-run)", "tags": [ "automation" ] } }, "/v1/actions/hospitality.action.pause_automation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_pause_automation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.pause_automation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_pause_automation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the automation is being paused", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.automation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Pause automation (rollup delta)", "tags": [ "automation" ] } }, "/v1/actions/hospitality.action.pause_channel_connection/apply": { "post": { "description": "Stop publishing on a conduit from our side — a credential rotation, a maintenance window, a mapping rebuild. Reversible with `resume_channel_connection`. Distinct from `suspend_channel_connection`, which records that the *partner* stopped us; collapsing the two would hide which side owns the remediation. Inbound reservations keep arriving while paused and are still recorded — a guest who already booked does not stop existing because we stopped publishing. Emits `channel_connection.paused`.\n\nEffects: modify hospitality.channel_connection.", "operationId": "apply_hospitality_action_pause_channel_connection", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "paused_reason": { "title": "Why publication is stopped", "type": "string" } }, "required": [ "paused_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.channel_connection" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.pause_channel_connection:apply" ] } ], "summary": "Pause channel connection", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.pause_channel_connection/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_pause_channel_connection` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.pause_channel_connection:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_pause_channel_connection", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "paused_reason": { "title": "Why publication is stopped", "type": "string" } }, "required": [ "paused_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.channel_connection" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Pause channel connection (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.pause_channel_connection/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_pause_channel_connection`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_pause_channel_connection", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "paused_reason": { "title": "Why publication is stopped", "type": "string" } }, "required": [ "paused_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Pause channel connection (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.pause_channel_connection/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_pause_channel_connection` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.pause_channel_connection:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_pause_channel_connection", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "paused_reason": { "title": "Why publication is stopped", "type": "string" } }, "required": [ "paused_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Pause channel connection (rollup delta)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.pause_connector/apply": { "post": { "description": "Pause an `active` connector — the ingest worker stops starting syncs for it. Reversible (`resume_connector`); `reason` is required and lands on `paused_reason` so the Explorer shows *why* the feed is dark (credential rotation, vendor maintenance). Emits `connector.paused`.\n\nEffects: modify hospitality.connector.", "operationId": "apply_hospitality_action_pause_connector", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the connector is being paused", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.connector" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.pause_connector:apply" ] } ], "summary": "Pause connector", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.pause_connector/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_pause_connector` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.pause_connector:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_pause_connector", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the connector is being paused", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.connector" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Pause connector (dry-run)", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.pause_connector/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_pause_connector`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_pause_connector", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the connector is being paused", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Pause connector (dry-run)", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.pause_connector/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_pause_connector` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.pause_connector:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_pause_connector", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the connector is being paused", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Pause connector (rollup delta)", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.pay_commission_batch/apply": { "post": { "description": "Pay every commission row that is due at this property, optionally limited to one agent or to stays up to a date. Held rows are passed over, and rows awaiting a channel's own invoice are never collected — an agency-model OTA bills us, so paying those here would settle the same commission twice. An agent whose total falls below their agreed minimum is skipped rather than sent a cheque that costs more than it carries.\n\nEffects: create hospitality.commission_payment_batch; modify hospitality.commission_detail; link hospitality.link.commission_detail_in_batch; link hospitality.link.commission_batch_for_property.", "operationId": "apply_hospitality_action_pay_commission_batch", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "company_id": { "format": "uuid", "title": "Pay only this agent", "type": "string", "x-aerandil-references": "hospitality.company" }, "method": { "enum": [ "check", "bank_transfer", "settlement_network", "manual" ], "title": "How the batch pays out", "type": "string" }, "reference": { "title": "Cheque number, transfer reference or clearinghouse batch id", "type": "string" }, "through_date": { "format": "date", "title": "Only rows accrued on or before this date", "type": "string" } }, "required": [ "method" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.commission_detail_in_batch", "hospitality.link.commission_batch_for_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.commission_payment_batch", "hospitality.commission_detail" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.pay_commission_batch:apply" ] } ], "summary": "Pay commission batch", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.pay_commission_batch/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_pay_commission_batch` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.pay_commission_batch:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_pay_commission_batch", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "company_id": { "format": "uuid", "title": "Pay only this agent", "type": "string", "x-aerandil-references": "hospitality.company" }, "method": { "enum": [ "check", "bank_transfer", "settlement_network", "manual" ], "title": "How the batch pays out", "type": "string" }, "reference": { "title": "Cheque number, transfer reference or clearinghouse batch id", "type": "string" }, "through_date": { "format": "date", "title": "Only rows accrued on or before this date", "type": "string" } }, "required": [ "method" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.commission_detail_in_batch", "hospitality.link.commission_batch_for_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.commission_payment_batch", "hospitality.commission_detail" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Pay commission batch (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.pay_commission_batch/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_pay_commission_batch`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_pay_commission_batch", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "company_id": { "format": "uuid", "title": "Pay only this agent", "type": "string", "x-aerandil-references": "hospitality.company" }, "method": { "enum": [ "check", "bank_transfer", "settlement_network", "manual" ], "title": "How the batch pays out", "type": "string" }, "reference": { "title": "Cheque number, transfer reference or clearinghouse batch id", "type": "string" }, "through_date": { "format": "date", "title": "Only rows accrued on or before this date", "type": "string" } }, "required": [ "method" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Pay commission batch (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.pay_commission_batch/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_pay_commission_batch` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.pay_commission_batch:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_pay_commission_batch", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "company_id": { "format": "uuid", "title": "Pay only this agent", "type": "string", "x-aerandil-references": "hospitality.company" }, "method": { "enum": [ "check", "bank_transfer", "settlement_network", "manual" ], "title": "How the batch pays out", "type": "string" }, "reference": { "title": "Cheque number, transfer reference or clearinghouse batch id", "type": "string" }, "through_date": { "format": "date", "title": "Only rows accrued on or before this date", "type": "string" } }, "required": [ "method" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Pay commission batch (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.pick_up_block_reservation/apply": { "post": { "description": "Attach a reservation to the block, drawing its nights from the block's own allotment rather than from house availability. Each night moves one room from `blocked` to `sold`, so the booking ceiling is unchanged. Refuses a night the block has no unpicked room left on. Idempotent: a reservation already picked up from this block is a no-op, so a retried batch cannot draw the allotment down twice.\n\nEffects: modify hospitality.block_allocation; modify hospitality.availability_day; link hospitality.link.reservation_picked_up_from_block.", "operationId": "apply_hospitality_action_pick_up_block_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reservation_id": { "format": "uuid", "title": "Reservation to attach", "type": "string", "x-aerandil-references": "hospitality.reservation" } }, "required": [ "reservation_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_block" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.reservation_picked_up_from_block" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.block_allocation", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.pick_up_block_reservation:apply" ] } ], "summary": "Pick up block reservation", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.pick_up_block_reservation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_pick_up_block_reservation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.pick_up_block_reservation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_pick_up_block_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reservation_id": { "format": "uuid", "title": "Reservation to attach", "type": "string", "x-aerandil-references": "hospitality.reservation" } }, "required": [ "reservation_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_block" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.reservation_picked_up_from_block" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.block_allocation", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Pick up block reservation (dry-run)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.pick_up_block_reservation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_pick_up_block_reservation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_pick_up_block_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reservation_id": { "format": "uuid", "title": "Reservation to attach", "type": "string", "x-aerandil-references": "hospitality.reservation" } }, "required": [ "reservation_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_block" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Pick up block reservation (dry-run)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.pick_up_block_reservation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_pick_up_block_reservation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.pick_up_block_reservation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_pick_up_block_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reservation_id": { "format": "uuid", "title": "Reservation to attach", "type": "string", "x-aerandil-references": "hospitality.reservation" } }, "required": [ "reservation_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_block" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Pick up block reservation (rollup delta)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.pin_object_property/apply": { "post": { "description": "Protect a property's current value (or current absence) from sourced writes: connector syncs mask the property back to its pinned state instead of overwriting it, until the pin is released. Only properties the schema declares `pinnable` may be pinned. The pin records who, when, and why — an override without a justification is unauditable. Direct human edits remain possible while pinned (the pin guards against sources, not operators) and re-pinning replaces the existing pin. Emits `object_property.pinned`.", "operationId": "apply_hospitality_action_pin_object_property", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "object_id": { "title": "Object id", "type": "string" }, "object_type": { "title": "Object type carrying the property", "type": "string" }, "property": { "title": "Property to pin (must be declared pinnable)", "type": "string" }, "reason": { "title": "Why the override exists (audit-required)", "type": "string" } }, "required": [ "object_type", "object_id", "property", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.pin_object_property:apply" ] } ], "summary": "Pin object property", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.pin_object_property/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_pin_object_property` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.pin_object_property:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_pin_object_property", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "object_id": { "title": "Object id", "type": "string" }, "object_type": { "title": "Object type carrying the property", "type": "string" }, "property": { "title": "Property to pin (must be declared pinnable)", "type": "string" }, "reason": { "title": "Why the override exists (audit-required)", "type": "string" } }, "required": [ "object_type", "object_id", "property", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Pin object property (dry-run)", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.pin_object_property/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_pin_object_property`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_pin_object_property", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "object_id": { "title": "Object id", "type": "string" }, "object_type": { "title": "Object type carrying the property", "type": "string" }, "property": { "title": "Property to pin (must be declared pinnable)", "type": "string" }, "reason": { "title": "Why the override exists (audit-required)", "type": "string" } }, "required": [ "object_type", "object_id", "property", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Pin object property (dry-run)", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.pin_object_property/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_pin_object_property` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.pin_object_property:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_pin_object_property", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "object_id": { "title": "Object id", "type": "string" }, "object_type": { "title": "Object type carrying the property", "type": "string" }, "property": { "title": "Property to pin (must be declared pinnable)", "type": "string" }, "reason": { "title": "Why the override exists (audit-required)", "type": "string" } }, "required": [ "object_type", "object_id", "property", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Pin object property (rollup delta)", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.post_banquet_event_charges/apply": { "post": { "description": "Post every line of an issued order as a charge: per-person lines at the billable count (the higher of the guarantee and the actual) times their quantity, fixed lines at their quantity, the service charge on food and beverage lines carried as the charge's gratuity leg. Needs the event `actual` and the order `issued` or `revised`. The charges go to the order's folio, else the block's master folio, and a routing rule bound there is obeyed; the folio must be open and in the order's currency. The order becomes `posted` and its lines freeze.\n\nEffects: create hospitality.charge; modify hospitality.folio; modify hospitality.banquet_event_order; link hospitality.link.folio_has_charge; link hospitality.link.charge_at_outlet; link hospitality.link.charge_for_service_item; link hospitality.link.banquet_order_line_posted_charge.", "operationId": "apply_hospitality_action_post_banquet_event_charges", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_event_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_charge", "hospitality.link.charge_at_outlet", "hospitality.link.charge_for_service_item", "hospitality.link.banquet_order_line_posted_charge" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.charge", "hospitality.folio", "hospitality.banquet_event_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.post_banquet_event_charges:apply" ] } ], "summary": "Post banquet event charges", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.post_banquet_event_charges/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_post_banquet_event_charges` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.post_banquet_event_charges:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_post_banquet_event_charges", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_event_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_charge", "hospitality.link.charge_at_outlet", "hospitality.link.charge_for_service_item", "hospitality.link.banquet_order_line_posted_charge" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.charge", "hospitality.folio", "hospitality.banquet_event_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Post banquet event charges (dry-run)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.post_banquet_event_charges/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_post_banquet_event_charges`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_post_banquet_event_charges", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_event_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Post banquet event charges (dry-run)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.post_banquet_event_charges/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_post_banquet_event_charges` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.post_banquet_event_charges:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_post_banquet_event_charges", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_event_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Post banquet event charges (rollup delta)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.post_cancellation_fee/apply": { "post": { "description": "Charge a cancelled booking what its terms said cancelling would cost. The amount defaults to the figure frozen at booking — the step of the ladder in force when the guest cancelled — so the desk charges what was disclosed rather than a number typed on the day; pass `amount` only to charge less. Posts under USALI miscellaneous income with `system_charge_kind = cancellation_fee`, onto the booking's own account, opened here because a cancelled booking never checks in. Taxed like every retained payment: by the rules the house authored for a `cancellation_fee`, and not at all where it authored none.\n\nThe sibling of the night audit's no-show fee, and deliberately not the same verb: a no-show is swept automatically at the close of the arrival day, while a cancellation is a decision someone makes. Apaleo splits them the same way, as two folio actions posting the same shape. Collecting the money afterwards is the card rail's `POST /v1/reservations/{id}/cancellation-fee/collection` (2026-10-27), which asks the card for what the account still owes after any deposit on it — or the ordinary folio payment surface, since the charge is on an account and an account is billable. Idempotent: a booking whose fee is already posted refuses a second one. A guest who cancelled before any step of the frozen ladder charged anything owes nothing, and is charged only an `amount` the desk states (`cancelled_outside_window` otherwise); an `amount` is capped at the step in force. Refused once the deposit was kept (`forfeit_deposit`): Keep and Charge are one decision.\n\nEffects: create hospitality.charge; link hospitality.link.charge_at_outlet; create hospitality.tax_application; link hospitality.link.charge_has_tax_application; create hospitality.folio; link hospitality.link.reservation_has_folio; link hospitality.link.folio_has_charge; modify hospitality.folio; modify hospitality.reservation.", "operationId": "apply_hospitality_action_post_cancellation_fee", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Fee charged", "type": "object" }, "business_date": { "format": "date", "title": "The business date the charge posts under", "type": "string" }, "outlet_id": { "format": "uuid", "title": "The miscellaneous-income outlet the fee reports under", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "reason_code": { "title": "Why, for the desk and the charge description", "type": "string" } }, "required": [ "business_date", "outlet_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.charge_at_outlet", "hospitality.link.charge_has_tax_application", "hospitality.link.reservation_has_folio", "hospitality.link.folio_has_charge" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.charge", "hospitality.tax_application", "hospitality.folio", "hospitality.reservation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.post_cancellation_fee:apply" ] } ], "summary": "Post cancellation fee", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.post_cancellation_fee/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_post_cancellation_fee` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.post_cancellation_fee:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_post_cancellation_fee", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Fee charged", "type": "object" }, "business_date": { "format": "date", "title": "The business date the charge posts under", "type": "string" }, "outlet_id": { "format": "uuid", "title": "The miscellaneous-income outlet the fee reports under", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "reason_code": { "title": "Why, for the desk and the charge description", "type": "string" } }, "required": [ "business_date", "outlet_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.charge_at_outlet", "hospitality.link.charge_has_tax_application", "hospitality.link.reservation_has_folio", "hospitality.link.folio_has_charge" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.charge", "hospitality.tax_application", "hospitality.folio", "hospitality.reservation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Post cancellation fee (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.post_cancellation_fee/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_post_cancellation_fee`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_post_cancellation_fee", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Fee charged", "type": "object" }, "business_date": { "format": "date", "title": "The business date the charge posts under", "type": "string" }, "outlet_id": { "format": "uuid", "title": "The miscellaneous-income outlet the fee reports under", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "reason_code": { "title": "Why, for the desk and the charge description", "type": "string" } }, "required": [ "business_date", "outlet_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Post cancellation fee (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.post_cancellation_fee/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_post_cancellation_fee` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.post_cancellation_fee:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_post_cancellation_fee", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Fee charged", "type": "object" }, "business_date": { "format": "date", "title": "The business date the charge posts under", "type": "string" }, "outlet_id": { "format": "uuid", "title": "The miscellaneous-income outlet the fee reports under", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "reason_code": { "title": "Why, for the desk and the charge description", "type": "string" } }, "required": [ "business_date", "outlet_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Post cancellation fee (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.post_charge/apply": { "post": { "description": "Post a charge line to a folio. `amount` is the charge's base amount — inclusive taxes (VAT-style) ride inside it, while exclusive tax lines and `gratuity` add on top, so the folio debit is amount + Σ(exclusive tax) + gratuity. Each `tax_lines` entry lands as a linked `tax_application` row for fiscal / OTA disclosure; the charge's aggregate `tax` is the sum of every line regardless of inclusivity.\n\nEffects: create hospitality.charge; create hospitality.tax_application; link hospitality.link.folio_has_charge; link hospitality.link.charge_has_tax_application; link hospitality.link.charge_for_service_item; link hospitality.link.charge_at_outlet; modify hospitality.folio.", "operationId": "apply_hospitality_action_post_charge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "USALI 12 department", "type": "string" }, "description": { "title": "Description", "type": "string" }, "gratuity": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Gratuity / service charge added on top of the amount", "type": "object" }, "outlet_id": { "format": "uuid", "title": "USALI 12 outlet the charge rolls up to (proposal 0023)", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "service_item_id": { "format": "uuid", "title": "Service item", "type": "string", "x-aerandil-references": "hospitality.service_item" }, "system_charge_kind": { "enum": [ "room_night", "day_use", "tax", "service_charge", "gratuity", "adjustment", "package_discount", "forfeited_deposit", "no_show_fee", "cancellation_fee", "no_show_revenue" ], "title": "System-generated charge kind", "type": "string" }, "tax_lines": { "items": { "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "basis_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "code": { "type": "string" }, "inclusive": { "type": "boolean" }, "jurisdiction": { "type": "string" }, "rate": { "format": "decimal", "type": "string" } }, "required": [ "code", "jurisdiction", "rate", "amount", "inclusive" ], "type": "object" }, "title": "Per-jurisdiction tax decomposition (each lands as a tax_application)", "type": "array" } }, "required": [ "description", "amount", "bucket", "outlet_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_charge", "hospitality.link.charge_has_tax_application", "hospitality.link.charge_for_service_item", "hospitality.link.charge_at_outlet" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.charge", "hospitality.tax_application", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.post_charge:apply" ] } ], "summary": "Post charge", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.post_charge/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_post_charge` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.post_charge:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_post_charge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "USALI 12 department", "type": "string" }, "description": { "title": "Description", "type": "string" }, "gratuity": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Gratuity / service charge added on top of the amount", "type": "object" }, "outlet_id": { "format": "uuid", "title": "USALI 12 outlet the charge rolls up to (proposal 0023)", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "service_item_id": { "format": "uuid", "title": "Service item", "type": "string", "x-aerandil-references": "hospitality.service_item" }, "system_charge_kind": { "enum": [ "room_night", "day_use", "tax", "service_charge", "gratuity", "adjustment", "package_discount", "forfeited_deposit", "no_show_fee", "cancellation_fee", "no_show_revenue" ], "title": "System-generated charge kind", "type": "string" }, "tax_lines": { "items": { "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "basis_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "code": { "type": "string" }, "inclusive": { "type": "boolean" }, "jurisdiction": { "type": "string" }, "rate": { "format": "decimal", "type": "string" } }, "required": [ "code", "jurisdiction", "rate", "amount", "inclusive" ], "type": "object" }, "title": "Per-jurisdiction tax decomposition (each lands as a tax_application)", "type": "array" } }, "required": [ "description", "amount", "bucket", "outlet_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_charge", "hospitality.link.charge_has_tax_application", "hospitality.link.charge_for_service_item", "hospitality.link.charge_at_outlet" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.charge", "hospitality.tax_application", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Post charge (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.post_charge/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_post_charge`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_post_charge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "USALI 12 department", "type": "string" }, "description": { "title": "Description", "type": "string" }, "gratuity": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Gratuity / service charge added on top of the amount", "type": "object" }, "outlet_id": { "format": "uuid", "title": "USALI 12 outlet the charge rolls up to (proposal 0023)", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "service_item_id": { "format": "uuid", "title": "Service item", "type": "string", "x-aerandil-references": "hospitality.service_item" }, "system_charge_kind": { "enum": [ "room_night", "day_use", "tax", "service_charge", "gratuity", "adjustment", "package_discount", "forfeited_deposit", "no_show_fee", "cancellation_fee", "no_show_revenue" ], "title": "System-generated charge kind", "type": "string" }, "tax_lines": { "items": { "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "basis_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "code": { "type": "string" }, "inclusive": { "type": "boolean" }, "jurisdiction": { "type": "string" }, "rate": { "format": "decimal", "type": "string" } }, "required": [ "code", "jurisdiction", "rate", "amount", "inclusive" ], "type": "object" }, "title": "Per-jurisdiction tax decomposition (each lands as a tax_application)", "type": "array" } }, "required": [ "description", "amount", "bucket", "outlet_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Post charge (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.post_charge/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_post_charge` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.post_charge:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_post_charge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "USALI 12 department", "type": "string" }, "description": { "title": "Description", "type": "string" }, "gratuity": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Gratuity / service charge added on top of the amount", "type": "object" }, "outlet_id": { "format": "uuid", "title": "USALI 12 outlet the charge rolls up to (proposal 0023)", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "service_item_id": { "format": "uuid", "title": "Service item", "type": "string", "x-aerandil-references": "hospitality.service_item" }, "system_charge_kind": { "enum": [ "room_night", "day_use", "tax", "service_charge", "gratuity", "adjustment", "package_discount", "forfeited_deposit", "no_show_fee", "cancellation_fee", "no_show_revenue" ], "title": "System-generated charge kind", "type": "string" }, "tax_lines": { "items": { "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "basis_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "code": { "type": "string" }, "inclusive": { "type": "boolean" }, "jurisdiction": { "type": "string" }, "rate": { "format": "decimal", "type": "string" } }, "required": [ "code", "jurisdiction", "rate", "amount", "inclusive" ], "type": "object" }, "title": "Per-jurisdiction tax decomposition (each lands as a tax_application)", "type": "array" } }, "required": [ "description", "amount", "bucket", "outlet_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Post charge (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.post_charge_by_credential/apply": { "post": { "description": "The tap: post a charge to a folio identified by an access-credential token instead of a folio id — the terminal reads the card UID, the kernel resolves token → active credential → in-house stay → open folio and posts through the same primitives as `post_charge` (bucket = the outlet's USALI department, `charge_at_outlet` + `charge_via_credential` linked, folio balance adjusted atomically). Requires an `active` registered device; enforces the credential's `per_charge_cap` and property-local-business-day `daily_cap`; holds the stay to its posting rules (`set_posting_rules`) as the till's tenders are held — a no-post stay refuses the tap (`no_post: …`), and so does one whose credit it would pass (`no_credit: …`), with no override on this path; fails closed with one generic error for unknown, revoked, expired, or checked-out credentials. The staff name-echo happens first via the `resolve_access_credential` function. Emits `charge.posted.recorded` with credential and device attribution.\n\nEffects: create hospitality.charge; link hospitality.link.folio_has_charge; link hospitality.link.charge_at_outlet; link hospitality.link.charge_via_credential; modify hospitality.folio.", "operationId": "apply_hospitality_action_post_charge_by_credential", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Charge amount", "type": "object" }, "description": { "title": "Charge description (defaults to the outlet name)", "type": "string" }, "device_id": { "format": "uuid", "title": "Registered terminal the tap happened on", "type": "string", "x-aerandil-references": "hospitality.device" }, "outlet_id": { "format": "uuid", "title": "Revenue center posting the charge", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "token": { "title": "Opaque vendor token read at tap time", "type": "string" } }, "required": [ "token", "outlet_id", "device_id", "amount" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_charge", "hospitality.link.charge_at_outlet", "hospitality.link.charge_via_credential" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.charge", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.post_charge_by_credential:apply" ] } ], "summary": "Post charge by credential", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.post_charge_by_credential/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_post_charge_by_credential` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.post_charge_by_credential:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_post_charge_by_credential", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Charge amount", "type": "object" }, "description": { "title": "Charge description (defaults to the outlet name)", "type": "string" }, "device_id": { "format": "uuid", "title": "Registered terminal the tap happened on", "type": "string", "x-aerandil-references": "hospitality.device" }, "outlet_id": { "format": "uuid", "title": "Revenue center posting the charge", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "token": { "title": "Opaque vendor token read at tap time", "type": "string" } }, "required": [ "token", "outlet_id", "device_id", "amount" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_charge", "hospitality.link.charge_at_outlet", "hospitality.link.charge_via_credential" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.charge", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Post charge by credential (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.post_charge_by_credential/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_post_charge_by_credential`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_post_charge_by_credential", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Charge amount", "type": "object" }, "description": { "title": "Charge description (defaults to the outlet name)", "type": "string" }, "device_id": { "format": "uuid", "title": "Registered terminal the tap happened on", "type": "string", "x-aerandil-references": "hospitality.device" }, "outlet_id": { "format": "uuid", "title": "Revenue center posting the charge", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "token": { "title": "Opaque vendor token read at tap time", "type": "string" } }, "required": [ "token", "outlet_id", "device_id", "amount" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Post charge by credential (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.post_charge_by_credential/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_post_charge_by_credential` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.post_charge_by_credential:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_post_charge_by_credential", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Charge amount", "type": "object" }, "description": { "title": "Charge description (defaults to the outlet name)", "type": "string" }, "device_id": { "format": "uuid", "title": "Registered terminal the tap happened on", "type": "string", "x-aerandil-references": "hospitality.device" }, "outlet_id": { "format": "uuid", "title": "Revenue center posting the charge", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "token": { "title": "Opaque vendor token read at tap time", "type": "string" } }, "required": [ "token", "outlet_id", "device_id", "amount" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Post charge by credential (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.post_departed_charge/apply": { "post": { "description": "Post charges found after the guest left — OPERA's Delayed Charges — to the departed stay's bill, inside the house's post-stay window (`set_post_stay_charging`). Each line posts as an ordinary charge on today's business date, through the house's sole outlet in the line's `bucket`, with the house's tax rules for that bucket; the bill is reopened first (`reopen_folio`, reason `late_charge`) when check-out closed it. A line naming the floor's `uncharged` minibar consumption (`movement_id`) is joined to the charge it became (`charge_for_stock_movement`), and a consumption already posted is skipped, so the same lines posted twice post once. Refused for a stay still in house, when the house has the window off, after the window closed, and when the bill has been invoiced (correct a sealed bill with `open_rebate_folio`). Taking the money is the card rail's (`POST /v1/stays/{id}/post-stay-charges/collection`). Emits `post_stay_charge.posted` with the bill's new balance.\n\nEffects: modify hospitality.folio; create hospitality.charge; link hospitality.link.folio_has_charge; link hospitality.link.charge_at_outlet; link hospitality.link.charge_for_service_item; create hospitality.tax_application; link hospitality.link.charge_has_tax_application; link hospitality.link.charge_for_stock_movement.", "operationId": "apply_hospitality_action_post_departed_charge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "lines": { "items": { "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "type": "string" }, "description": { "type": "string" }, "movement_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.stock_movement" } }, "required": [ "description", "amount", "bucket" ], "type": "object" }, "title": "What was found: description, amount, bucket, and the minibar movement it bills", "type": "array" }, "note": { "title": "What the desk wants the bill's reopening to say", "type": "string" }, "reason": { "enum": [ "minibar", "damage", "laundry", "other" ], "title": "minibar, damage, laundry or other", "type": "string" } }, "required": [ "lines", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_charge", "hospitality.link.charge_at_outlet", "hospitality.link.charge_for_service_item", "hospitality.link.charge_has_tax_application", "hospitality.link.charge_for_stock_movement" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.folio", "hospitality.charge", "hospitality.tax_application" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.post_departed_charge:apply" ] } ], "summary": "Post departed charge", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.post_departed_charge/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_post_departed_charge` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.post_departed_charge:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_post_departed_charge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "lines": { "items": { "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "type": "string" }, "description": { "type": "string" }, "movement_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.stock_movement" } }, "required": [ "description", "amount", "bucket" ], "type": "object" }, "title": "What was found: description, amount, bucket, and the minibar movement it bills", "type": "array" }, "note": { "title": "What the desk wants the bill's reopening to say", "type": "string" }, "reason": { "enum": [ "minibar", "damage", "laundry", "other" ], "title": "minibar, damage, laundry or other", "type": "string" } }, "required": [ "lines", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_charge", "hospitality.link.charge_at_outlet", "hospitality.link.charge_for_service_item", "hospitality.link.charge_has_tax_application", "hospitality.link.charge_for_stock_movement" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.folio", "hospitality.charge", "hospitality.tax_application" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Post departed charge (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.post_departed_charge/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_post_departed_charge`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_post_departed_charge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "lines": { "items": { "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "type": "string" }, "description": { "type": "string" }, "movement_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.stock_movement" } }, "required": [ "description", "amount", "bucket" ], "type": "object" }, "title": "What was found: description, amount, bucket, and the minibar movement it bills", "type": "array" }, "note": { "title": "What the desk wants the bill's reopening to say", "type": "string" }, "reason": { "enum": [ "minibar", "damage", "laundry", "other" ], "title": "minibar, damage, laundry or other", "type": "string" } }, "required": [ "lines", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Post departed charge (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.post_departed_charge/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_post_departed_charge` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.post_departed_charge:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_post_departed_charge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "lines": { "items": { "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "type": "string" }, "description": { "type": "string" }, "movement_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.stock_movement" } }, "required": [ "description", "amount", "bucket" ], "type": "object" }, "title": "What was found: description, amount, bucket, and the minibar movement it bills", "type": "array" }, "note": { "title": "What the desk wants the bill's reopening to say", "type": "string" }, "reason": { "enum": [ "minibar", "damage", "laundry", "other" ], "title": "minibar, damage, laundry or other", "type": "string" } }, "required": [ "lines", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Post departed charge (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.post_external_charge/apply": { "post": { "description": "Post a vendor-sourced charge to the folio of a reservation's stay (window 1 unless `window_number` says otherwise) — or, while the booking has no stay yet (a fee on a booking that cancelled or never came, a line sold before arrival), to the booking's own account, opened on first use, as `post_cancellation_fee` posts. Business time: `posted_at` is when the source system posted the charge, defaulting to now. Replay-safe via `external_ref` (the charge business key): a crashed-pass retry lands on the existing charge instead of double-debiting the folio. Accepts a closed folio — a vendor's back-posted history is recorded, not refused. `outlet_id` may be omitted, in which case the property's sole outlet in the charge's USALI `bucket` is resolved (ambiguity refuses loudly — the 0023 charge-to-outlet attribution contract holds either way).\n\nEffects: create hospitality.charge; link hospitality.link.folio_has_charge; link hospitality.link.charge_at_outlet; modify hospitality.folio; create hospitality.folio; link hospitality.link.reservation_has_folio.", "operationId": "apply_hospitality_action_post_external_charge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "USALI 12 department", "type": "string" }, "description": { "title": "Description", "type": "string" }, "external_ref": { "title": "Source-system key (makes the post replay-safe)", "type": "string" }, "outlet_id": { "format": "uuid", "title": "Outlet (omit to resolve the property's sole outlet in `bucket`)", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "posted_at": { "format": "date-time", "title": "Posting instant in the source system (defaults to now)", "type": "string" }, "reservation_id": { "format": "uuid", "title": "Reservation whose stay folio receives the charge", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "reservation_room_id": { "format": "uuid", "title": "Leg whose stay folio receives the charge (required when the reservation has more than one stay)", "type": "string", "x-aerandil-references": "hospitality.reservation_room" }, "system_charge_kind": { "enum": [ "room_night", "day_use", "tax", "service_charge", "gratuity", "adjustment", "package_discount", "forfeited_deposit", "no_show_fee", "cancellation_fee", "no_show_revenue" ], "title": "System-generated charge kind", "type": "string" }, "window_number": { "title": "Folio window (defaults to 1)", "type": "integer" } }, "required": [ "reservation_id", "description", "amount", "bucket" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_charge", "hospitality.link.charge_at_outlet", "hospitality.link.reservation_has_folio" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.charge", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.post_external_charge:apply" ] } ], "summary": "Post external charge", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.post_external_charge/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_post_external_charge` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.post_external_charge:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_post_external_charge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "USALI 12 department", "type": "string" }, "description": { "title": "Description", "type": "string" }, "external_ref": { "title": "Source-system key (makes the post replay-safe)", "type": "string" }, "outlet_id": { "format": "uuid", "title": "Outlet (omit to resolve the property's sole outlet in `bucket`)", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "posted_at": { "format": "date-time", "title": "Posting instant in the source system (defaults to now)", "type": "string" }, "reservation_id": { "format": "uuid", "title": "Reservation whose stay folio receives the charge", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "reservation_room_id": { "format": "uuid", "title": "Leg whose stay folio receives the charge (required when the reservation has more than one stay)", "type": "string", "x-aerandil-references": "hospitality.reservation_room" }, "system_charge_kind": { "enum": [ "room_night", "day_use", "tax", "service_charge", "gratuity", "adjustment", "package_discount", "forfeited_deposit", "no_show_fee", "cancellation_fee", "no_show_revenue" ], "title": "System-generated charge kind", "type": "string" }, "window_number": { "title": "Folio window (defaults to 1)", "type": "integer" } }, "required": [ "reservation_id", "description", "amount", "bucket" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_charge", "hospitality.link.charge_at_outlet", "hospitality.link.reservation_has_folio" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.charge", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Post external charge (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.post_external_charge/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_post_external_charge`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_post_external_charge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "USALI 12 department", "type": "string" }, "description": { "title": "Description", "type": "string" }, "external_ref": { "title": "Source-system key (makes the post replay-safe)", "type": "string" }, "outlet_id": { "format": "uuid", "title": "Outlet (omit to resolve the property's sole outlet in `bucket`)", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "posted_at": { "format": "date-time", "title": "Posting instant in the source system (defaults to now)", "type": "string" }, "reservation_id": { "format": "uuid", "title": "Reservation whose stay folio receives the charge", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "reservation_room_id": { "format": "uuid", "title": "Leg whose stay folio receives the charge (required when the reservation has more than one stay)", "type": "string", "x-aerandil-references": "hospitality.reservation_room" }, "system_charge_kind": { "enum": [ "room_night", "day_use", "tax", "service_charge", "gratuity", "adjustment", "package_discount", "forfeited_deposit", "no_show_fee", "cancellation_fee", "no_show_revenue" ], "title": "System-generated charge kind", "type": "string" }, "window_number": { "title": "Folio window (defaults to 1)", "type": "integer" } }, "required": [ "reservation_id", "description", "amount", "bucket" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Post external charge (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.post_external_charge/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_post_external_charge` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.post_external_charge:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_post_external_charge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "USALI 12 department", "type": "string" }, "description": { "title": "Description", "type": "string" }, "external_ref": { "title": "Source-system key (makes the post replay-safe)", "type": "string" }, "outlet_id": { "format": "uuid", "title": "Outlet (omit to resolve the property's sole outlet in `bucket`)", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "posted_at": { "format": "date-time", "title": "Posting instant in the source system (defaults to now)", "type": "string" }, "reservation_id": { "format": "uuid", "title": "Reservation whose stay folio receives the charge", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "reservation_room_id": { "format": "uuid", "title": "Leg whose stay folio receives the charge (required when the reservation has more than one stay)", "type": "string", "x-aerandil-references": "hospitality.reservation_room" }, "system_charge_kind": { "enum": [ "room_night", "day_use", "tax", "service_charge", "gratuity", "adjustment", "package_discount", "forfeited_deposit", "no_show_fee", "cancellation_fee", "no_show_revenue" ], "title": "System-generated charge kind", "type": "string" }, "window_number": { "title": "Folio window (defaults to 1)", "type": "integer" } }, "required": [ "reservation_id", "description", "amount", "bucket" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Post external charge (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.post_housekeeping_briefing/apply": { "post": { "description": "Post the head housekeeper's instructions for a day to the floor (hubOS's 'indications'). The author is the staff member behind the session; a caller that is not one (an agent, the desk without a staff record) names the author with `author_id` — a supervisor (housekeeping or front-office supervisor, manager on duty, general manager, owner) at the house. `business_date` defaults to the house's today. Replay-safe per property × date × author: the same text again writes nothing; different text is a second briefing, never an edit — readers list a day's briefings newest first by `posted_at`. Emits `housekeeping.briefing.posted`.\n\nEffects: create hospitality.housekeeping_briefing; link hospitality.link.housekeeping_briefing_at_property; link hospitality.link.housekeeping_briefing_by.", "operationId": "apply_hospitality_action_post_housekeeping_briefing", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "author_id": { "format": "uuid", "title": "Author — a supervisor at the house — when the caller is not a staff member", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "business_date": { "format": "date", "title": "The house's day it is for (defaults to today at the house)", "type": "string" }, "text": { "title": "The instructions", "type": "string" } }, "required": [ "text" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.housekeeping_briefing_at_property", "hospitality.link.housekeeping_briefing_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.housekeeping_briefing" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.post_housekeeping_briefing:apply" ] } ], "summary": "Post housekeeping briefing", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.post_housekeeping_briefing/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_post_housekeeping_briefing` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.post_housekeeping_briefing:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_post_housekeeping_briefing", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "author_id": { "format": "uuid", "title": "Author — a supervisor at the house — when the caller is not a staff member", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "business_date": { "format": "date", "title": "The house's day it is for (defaults to today at the house)", "type": "string" }, "text": { "title": "The instructions", "type": "string" } }, "required": [ "text" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.housekeeping_briefing_at_property", "hospitality.link.housekeeping_briefing_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.housekeeping_briefing" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Post housekeeping briefing (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.post_housekeeping_briefing/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_post_housekeeping_briefing`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_post_housekeeping_briefing", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "author_id": { "format": "uuid", "title": "Author — a supervisor at the house — when the caller is not a staff member", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "business_date": { "format": "date", "title": "The house's day it is for (defaults to today at the house)", "type": "string" }, "text": { "title": "The instructions", "type": "string" } }, "required": [ "text" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Post housekeeping briefing (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.post_housekeeping_briefing/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_post_housekeeping_briefing` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.post_housekeeping_briefing:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_post_housekeeping_briefing", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "author_id": { "format": "uuid", "title": "Author — a supervisor at the house — when the caller is not a staff member", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "business_date": { "format": "date", "title": "The house's day it is for (defaults to today at the house)", "type": "string" }, "text": { "title": "The instructions", "type": "string" } }, "required": [ "text" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Post housekeeping briefing (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.post_package_profit_loss/apply": { "post": { "description": "Post the package's wrapper-vs-components reconciliation charge at night-audit close (Opera package_profit / package_loss). The resulting charge carries `package_attribution_kind = package_discount_adjustment`.\n\nEffects: create hospitality.charge; link hospitality.link.folio_has_charge; link hospitality.link.charge_attributed_to_package_sale; link hospitality.link.charge_at_outlet.", "operationId": "apply_hospitality_action_post_package_profit_loss", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Adjustment amount (signed)", "type": "object" }, "bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "USALI 12 department", "type": "string" }, "description": { "title": "Charge description", "type": "string" }, "folio_id": { "format": "uuid", "title": "Folio receiving the adjustment", "type": "string", "x-aerandil-references": "hospitality.folio" }, "outlet_id": { "format": "uuid", "title": "USALI 12 outlet the adjustment rolls up to (proposal 0023)", "type": "string", "x-aerandil-references": "hospitality.outlet" } }, "required": [ "folio_id", "amount", "bucket", "description", "outlet_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.package_sale" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_charge", "hospitality.link.charge_attributed_to_package_sale", "hospitality.link.charge_at_outlet" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.charge" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.post_package_profit_loss:apply" ] } ], "summary": "Post package profit / loss adjustment", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.post_package_profit_loss/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_post_package_profit_loss` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.post_package_profit_loss:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_post_package_profit_loss", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Adjustment amount (signed)", "type": "object" }, "bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "USALI 12 department", "type": "string" }, "description": { "title": "Charge description", "type": "string" }, "folio_id": { "format": "uuid", "title": "Folio receiving the adjustment", "type": "string", "x-aerandil-references": "hospitality.folio" }, "outlet_id": { "format": "uuid", "title": "USALI 12 outlet the adjustment rolls up to (proposal 0023)", "type": "string", "x-aerandil-references": "hospitality.outlet" } }, "required": [ "folio_id", "amount", "bucket", "description", "outlet_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.package_sale" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_charge", "hospitality.link.charge_attributed_to_package_sale", "hospitality.link.charge_at_outlet" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.charge" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Post package profit / loss adjustment (dry-run)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.post_package_profit_loss/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_post_package_profit_loss`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_post_package_profit_loss", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Adjustment amount (signed)", "type": "object" }, "bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "USALI 12 department", "type": "string" }, "description": { "title": "Charge description", "type": "string" }, "folio_id": { "format": "uuid", "title": "Folio receiving the adjustment", "type": "string", "x-aerandil-references": "hospitality.folio" }, "outlet_id": { "format": "uuid", "title": "USALI 12 outlet the adjustment rolls up to (proposal 0023)", "type": "string", "x-aerandil-references": "hospitality.outlet" } }, "required": [ "folio_id", "amount", "bucket", "description", "outlet_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.package_sale" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Post package profit / loss adjustment (dry-run)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.post_package_profit_loss/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_post_package_profit_loss` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.post_package_profit_loss:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_post_package_profit_loss", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Adjustment amount (signed)", "type": "object" }, "bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "USALI 12 department", "type": "string" }, "description": { "title": "Charge description", "type": "string" }, "folio_id": { "format": "uuid", "title": "Folio receiving the adjustment", "type": "string", "x-aerandil-references": "hospitality.folio" }, "outlet_id": { "format": "uuid", "title": "USALI 12 outlet the adjustment rolls up to (proposal 0023)", "type": "string", "x-aerandil-references": "hospitality.outlet" } }, "required": [ "folio_id", "amount", "bucket", "description", "outlet_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.package_sale" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Post package profit / loss adjustment (rollup delta)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.postpone_work_order/apply": { "post": { "description": "Defer the work to a named date, with the reason — hubOS's postponed fault. open / scheduled / blocked → postponed, stamping postponed_until (a day still to come at the house: never before the hotel date, and refused once its local midnight has passed — so tomorrow or later; a wait within the day is block_work_order), postponed_until_at (the house's local midnight starting that date) and postpone_reason on the order and writing a `postponement` line on its thread in the same transaction. Postponing a postponed order again moves the date (another line); repeating the same date and reason is a no-op. resume_work_order brings it back to open — the standing sweep fires it when postponed_until_at passes — and schedule_work_order or start_work_order resume it too; complete and void still apply. A held out-of-order block keeps its own dates — postponing the repair does not move the room's downtime.\n\nEffects: modify hospitality.work_order; create hospitality.work_order_entry; link hospitality.link.work_order_entry_for_work_order; link hospitality.link.work_order_entry_recorded_by.", "operationId": "apply_hospitality_action_postpone_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "postponed_until": { "format": "date", "title": "The date the work is deferred to", "type": "string" }, "reason": { "title": "Why the work is deferred", "type": "string" } }, "required": [ "postponed_until", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.work_order_entry_for_work_order", "hospitality.link.work_order_entry_recorded_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.work_order", "hospitality.work_order_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.postpone_work_order:apply" ] } ], "summary": "Postpone work order", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.postpone_work_order/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_postpone_work_order` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.postpone_work_order:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_postpone_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "postponed_until": { "format": "date", "title": "The date the work is deferred to", "type": "string" }, "reason": { "title": "Why the work is deferred", "type": "string" } }, "required": [ "postponed_until", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.work_order_entry_for_work_order", "hospitality.link.work_order_entry_recorded_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.work_order", "hospitality.work_order_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Postpone work order (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.postpone_work_order/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_postpone_work_order`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_postpone_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "postponed_until": { "format": "date", "title": "The date the work is deferred to", "type": "string" }, "reason": { "title": "Why the work is deferred", "type": "string" } }, "required": [ "postponed_until", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Postpone work order (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.postpone_work_order/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_postpone_work_order` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.postpone_work_order:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_postpone_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "postponed_until": { "format": "date", "title": "The date the work is deferred to", "type": "string" }, "reason": { "title": "Why the work is deferred", "type": "string" } }, "required": [ "postponed_until", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Postpone work order (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.prescribe_protocol/apply": { "post": { "description": "Prescribe a wellness protocol for the target membership. Creates the protocol row, links it to the membership, and attaches the typed modality references via `protocol_references_modalities` (a single protocol may reference multiple modalities — HBOT 2×/week + contrast bathing 3×/week + resistance training daily).\n\nEffects: create hospitality.wellness_protocol; link hospitality.link.wellness_protocol_for_membership; link hospitality.link.protocol_references_modalities.", "operationId": "apply_hospitality_action_prescribe_protocol", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "duration_weeks": { "title": "Protocol duration (weeks; null for open-ended)", "type": "integer" }, "frequency_per_week": { "title": "Sessions per week", "type": "integer" }, "goals_text": { "title": "Member's stated goals", "type": "string" }, "modality_ids": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.wellness_modality" }, "title": "Modalities referenced by this protocol — HBOT 2×/week + contrast bathing 3×/week + resistance training daily would pass three refs. Optional; lifestyle-only protocols ship with an empty array and rely on `goals_text` for the narrative shape", "type": "array" }, "prescribing_practitioner_text": { "title": "Practitioner who prescribed", "type": "string" } }, "required": [ "frequency_per_week", "prescribing_practitioner_text" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.wellness_protocol_for_membership", "hospitality.link.protocol_references_modalities" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.wellness_protocol" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.prescribe_protocol:apply" ] } ], "summary": "Prescribe protocol", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.prescribe_protocol/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_prescribe_protocol` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.prescribe_protocol:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_prescribe_protocol", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "duration_weeks": { "title": "Protocol duration (weeks; null for open-ended)", "type": "integer" }, "frequency_per_week": { "title": "Sessions per week", "type": "integer" }, "goals_text": { "title": "Member's stated goals", "type": "string" }, "modality_ids": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.wellness_modality" }, "title": "Modalities referenced by this protocol — HBOT 2×/week + contrast bathing 3×/week + resistance training daily would pass three refs. Optional; lifestyle-only protocols ship with an empty array and rely on `goals_text` for the narrative shape", "type": "array" }, "prescribing_practitioner_text": { "title": "Practitioner who prescribed", "type": "string" } }, "required": [ "frequency_per_week", "prescribing_practitioner_text" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.wellness_protocol_for_membership", "hospitality.link.protocol_references_modalities" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.wellness_protocol" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Prescribe protocol (dry-run)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.prescribe_protocol/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_prescribe_protocol`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_prescribe_protocol", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "duration_weeks": { "title": "Protocol duration (weeks; null for open-ended)", "type": "integer" }, "frequency_per_week": { "title": "Sessions per week", "type": "integer" }, "goals_text": { "title": "Member's stated goals", "type": "string" }, "modality_ids": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.wellness_modality" }, "title": "Modalities referenced by this protocol — HBOT 2×/week + contrast bathing 3×/week + resistance training daily would pass three refs. Optional; lifestyle-only protocols ship with an empty array and rely on `goals_text` for the narrative shape", "type": "array" }, "prescribing_practitioner_text": { "title": "Practitioner who prescribed", "type": "string" } }, "required": [ "frequency_per_week", "prescribing_practitioner_text" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Prescribe protocol (dry-run)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.prescribe_protocol/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_prescribe_protocol` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.prescribe_protocol:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_prescribe_protocol", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "duration_weeks": { "title": "Protocol duration (weeks; null for open-ended)", "type": "integer" }, "frequency_per_week": { "title": "Sessions per week", "type": "integer" }, "goals_text": { "title": "Member's stated goals", "type": "string" }, "modality_ids": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.wellness_modality" }, "title": "Modalities referenced by this protocol — HBOT 2×/week + contrast bathing 3×/week + resistance training daily would pass three refs. Optional; lifestyle-only protocols ship with an empty array and rely on `goals_text` for the narrative shape", "type": "array" }, "prescribing_practitioner_text": { "title": "Practitioner who prescribed", "type": "string" } }, "required": [ "frequency_per_week", "prescribing_practitioner_text" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Prescribe protocol (rollup delta)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.propose_action/apply": { "post": { "description": "An agent creates a `proposed_action` in `proposed` state: a frozen, auditable record of a registered action it intends to fire, surfaced for human/guest confirmation. Auto-supersedes a prior `proposed` record for the same `(target_action, subject_ref)`. Honours target_action_registered, proposer_scope, params_snapshot_required, no_high_risk_payload (§6). Emits `proposed_action.proposed`.\n\nEffects: create hospitality.proposed_action; modify hospitality.proposed_action; link hospitality.link.proposed_action_superseded_by.", "operationId": "apply_hospitality_action_propose_action", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "confidence": { "enum": [ "low", "medium", "high" ], "title": "Agent confidence in the proposal", "type": "string" }, "context_snapshot": { "additionalProperties": true, "title": "Frozen context the agent saw (bounded excerpts only)", "type": "object" }, "expires_at": { "format": "date-time", "title": "When an unconfirmed proposal sweeps to `expired` (default 24h)", "type": "string" }, "rationale_text": { "title": "Human-readable 'why', surfaced at confirmation time", "type": "string" }, "requires_confirmation_from": { "enum": [ "guest", "staff", "approval_gate" ], "title": "Who must confirm before the kernel fires the action", "type": "string" }, "subject_kind": { "enum": [ "reservation", "person", "folio", "charge", "stay", "venue", "other" ], "title": "The object class the action targets", "type": "string" }, "subject_ref": { "title": "Id of the subject object", "type": "string" }, "target_action": { "title": "The registered action this proposal intends to fire (ApiName form)", "type": "string" }, "target_params_snapshot": { "additionalProperties": true, "title": "Frozen proposed parameters for the target action", "type": "object" } }, "required": [ "target_action", "target_params_snapshot", "subject_kind", "subject_ref", "rationale_text", "context_snapshot", "confidence", "requires_confirmation_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.proposed_action_superseded_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.proposed_action" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.propose_action:apply" ] } ], "summary": "Propose action", "tags": [ "proposed_action" ] } }, "/v1/actions/hospitality.action.propose_action/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_propose_action` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.propose_action:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_propose_action", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "confidence": { "enum": [ "low", "medium", "high" ], "title": "Agent confidence in the proposal", "type": "string" }, "context_snapshot": { "additionalProperties": true, "title": "Frozen context the agent saw (bounded excerpts only)", "type": "object" }, "expires_at": { "format": "date-time", "title": "When an unconfirmed proposal sweeps to `expired` (default 24h)", "type": "string" }, "rationale_text": { "title": "Human-readable 'why', surfaced at confirmation time", "type": "string" }, "requires_confirmation_from": { "enum": [ "guest", "staff", "approval_gate" ], "title": "Who must confirm before the kernel fires the action", "type": "string" }, "subject_kind": { "enum": [ "reservation", "person", "folio", "charge", "stay", "venue", "other" ], "title": "The object class the action targets", "type": "string" }, "subject_ref": { "title": "Id of the subject object", "type": "string" }, "target_action": { "title": "The registered action this proposal intends to fire (ApiName form)", "type": "string" }, "target_params_snapshot": { "additionalProperties": true, "title": "Frozen proposed parameters for the target action", "type": "object" } }, "required": [ "target_action", "target_params_snapshot", "subject_kind", "subject_ref", "rationale_text", "context_snapshot", "confidence", "requires_confirmation_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.proposed_action_superseded_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.proposed_action" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Propose action (dry-run)", "tags": [ "proposed_action" ] } }, "/v1/actions/hospitality.action.propose_action/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_propose_action`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_propose_action", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "confidence": { "enum": [ "low", "medium", "high" ], "title": "Agent confidence in the proposal", "type": "string" }, "context_snapshot": { "additionalProperties": true, "title": "Frozen context the agent saw (bounded excerpts only)", "type": "object" }, "expires_at": { "format": "date-time", "title": "When an unconfirmed proposal sweeps to `expired` (default 24h)", "type": "string" }, "rationale_text": { "title": "Human-readable 'why', surfaced at confirmation time", "type": "string" }, "requires_confirmation_from": { "enum": [ "guest", "staff", "approval_gate" ], "title": "Who must confirm before the kernel fires the action", "type": "string" }, "subject_kind": { "enum": [ "reservation", "person", "folio", "charge", "stay", "venue", "other" ], "title": "The object class the action targets", "type": "string" }, "subject_ref": { "title": "Id of the subject object", "type": "string" }, "target_action": { "title": "The registered action this proposal intends to fire (ApiName form)", "type": "string" }, "target_params_snapshot": { "additionalProperties": true, "title": "Frozen proposed parameters for the target action", "type": "object" } }, "required": [ "target_action", "target_params_snapshot", "subject_kind", "subject_ref", "rationale_text", "context_snapshot", "confidence", "requires_confirmation_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Propose action (dry-run)", "tags": [ "proposed_action" ] } }, "/v1/actions/hospitality.action.propose_action/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_propose_action` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.propose_action:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_propose_action", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "confidence": { "enum": [ "low", "medium", "high" ], "title": "Agent confidence in the proposal", "type": "string" }, "context_snapshot": { "additionalProperties": true, "title": "Frozen context the agent saw (bounded excerpts only)", "type": "object" }, "expires_at": { "format": "date-time", "title": "When an unconfirmed proposal sweeps to `expired` (default 24h)", "type": "string" }, "rationale_text": { "title": "Human-readable 'why', surfaced at confirmation time", "type": "string" }, "requires_confirmation_from": { "enum": [ "guest", "staff", "approval_gate" ], "title": "Who must confirm before the kernel fires the action", "type": "string" }, "subject_kind": { "enum": [ "reservation", "person", "folio", "charge", "stay", "venue", "other" ], "title": "The object class the action targets", "type": "string" }, "subject_ref": { "title": "Id of the subject object", "type": "string" }, "target_action": { "title": "The registered action this proposal intends to fire (ApiName form)", "type": "string" }, "target_params_snapshot": { "additionalProperties": true, "title": "Frozen proposed parameters for the target action", "type": "object" } }, "required": [ "target_action", "target_params_snapshot", "subject_kind", "subject_ref", "rationale_text", "context_snapshot", "confidence", "requires_confirmation_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Propose action (rollup delta)", "tags": [ "proposed_action" ] } }, "/v1/actions/hospitality.action.propose_person_match/apply": { "post": { "description": "Create a `person_merge_candidate` proposing that two person rows are the same human. Callable by resolvers (over MCP) or an operator. Idempotent on the unordered pair while a `pending` candidate exists; a `rejected` pair is permanently suppressed from re-proposal unless `match_method = manual` (a human re-asserting the match is the explicit override — proposal 0027 §8.3). Emits `person.match_proposed`.\n\nEffects: create hospitality.person_merge_candidate.", "operationId": "apply_hospitality_action_propose_person_match", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "match_method": { "enum": [ "deterministic_email", "deterministic_loyalty_id", "deterministic_phone", "probabilistic_name_dob", "probabilistic_fuzzy", "manual" ], "title": "How the candidate was surfaced", "type": "string" }, "match_score": { "format": "decimal", "title": "Match confidence in [0, 1] (1.0 for deterministic / manual)", "type": "string" }, "matched_attributes": { "items": { "type": "string" }, "title": "Attribute names the match keyed on (names only, never values)", "type": "array" }, "person_a": { "format": "uuid", "title": "First person of the proposed pair", "type": "string", "x-aerandil-references": "hospitality.person" }, "person_b": { "format": "uuid", "title": "Second person of the proposed pair", "type": "string", "x-aerandil-references": "hospitality.person" } }, "required": [ "person_a", "person_b", "match_score", "match_method" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.person_merge_candidate" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.propose_person_match:apply" ] } ], "summary": "Propose person match", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.propose_person_match/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_propose_person_match` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.propose_person_match:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_propose_person_match", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "match_method": { "enum": [ "deterministic_email", "deterministic_loyalty_id", "deterministic_phone", "probabilistic_name_dob", "probabilistic_fuzzy", "manual" ], "title": "How the candidate was surfaced", "type": "string" }, "match_score": { "format": "decimal", "title": "Match confidence in [0, 1] (1.0 for deterministic / manual)", "type": "string" }, "matched_attributes": { "items": { "type": "string" }, "title": "Attribute names the match keyed on (names only, never values)", "type": "array" }, "person_a": { "format": "uuid", "title": "First person of the proposed pair", "type": "string", "x-aerandil-references": "hospitality.person" }, "person_b": { "format": "uuid", "title": "Second person of the proposed pair", "type": "string", "x-aerandil-references": "hospitality.person" } }, "required": [ "person_a", "person_b", "match_score", "match_method" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.person_merge_candidate" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Propose person match (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.propose_person_match/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_propose_person_match`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_propose_person_match", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "match_method": { "enum": [ "deterministic_email", "deterministic_loyalty_id", "deterministic_phone", "probabilistic_name_dob", "probabilistic_fuzzy", "manual" ], "title": "How the candidate was surfaced", "type": "string" }, "match_score": { "format": "decimal", "title": "Match confidence in [0, 1] (1.0 for deterministic / manual)", "type": "string" }, "matched_attributes": { "items": { "type": "string" }, "title": "Attribute names the match keyed on (names only, never values)", "type": "array" }, "person_a": { "format": "uuid", "title": "First person of the proposed pair", "type": "string", "x-aerandil-references": "hospitality.person" }, "person_b": { "format": "uuid", "title": "Second person of the proposed pair", "type": "string", "x-aerandil-references": "hospitality.person" } }, "required": [ "person_a", "person_b", "match_score", "match_method" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Propose person match (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.propose_person_match/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_propose_person_match` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.propose_person_match:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_propose_person_match", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "match_method": { "enum": [ "deterministic_email", "deterministic_loyalty_id", "deterministic_phone", "probabilistic_name_dob", "probabilistic_fuzzy", "manual" ], "title": "How the candidate was surfaced", "type": "string" }, "match_score": { "format": "decimal", "title": "Match confidence in [0, 1] (1.0 for deterministic / manual)", "type": "string" }, "matched_attributes": { "items": { "type": "string" }, "title": "Attribute names the match keyed on (names only, never values)", "type": "array" }, "person_a": { "format": "uuid", "title": "First person of the proposed pair", "type": "string", "x-aerandil-references": "hospitality.person" }, "person_b": { "format": "uuid", "title": "Second person of the proposed pair", "type": "string", "x-aerandil-references": "hospitality.person" } }, "required": [ "person_a", "person_b", "match_score", "match_method" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Propose person match (rollup delta)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.publish_federated_analysis_definition/apply": { "post": { "description": "Create a new immutable definition version or move a draft into review. Validates field allowlist, forbidden field classes, contribution bounds, privacy mechanisms, and output schema. Freezes local_code_digest, local_feature_contract, and privacy settings for this version. Validators (commit 5): `definition_input_field_allowlist_excludes_forbidden_classes`, `definition_cross_tenant_requires_cohort_threshold`, `definition_person_affecting_requires_dp_or_waiver`, `definition_federated_learning_requires_cards_and_clipping`, `definition_local_code_digest_required_when_reference_set`, `definition_none_threshold_only_internal_portfolio_only`.\n\nEffects: create hospitality.federated_analysis_definition; link hospitality.link.federated_program_has_definition.", "operationId": "apply_hospitality_action_publish_federated_analysis_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "aggregation_method": { "enum": [ "plain_aggregate_reviewed", "secure_sum", "noisy_count", "noisy_sum", "noisy_mean", "noisy_histogram", "noisy_quantile", "trimmed_mean", "weighted_average", "fedavg", "external_clean_room", "reviewed_custom" ], "title": "Aggregation method", "type": "string" }, "algorithm_family": { "enum": [ "secure_sum", "count_rate", "histogram", "quantile", "calibration_curve", "outcome_decay", "fedavg", "fedxgb", "reviewed_custom" ], "title": "Algorithm family", "type": "string" }, "analysis_kind": { "enum": [ "federated_analytics", "federated_learning", "private_set_intersection", "clean_room_query", "benchmark_export" ], "title": "Analysis kind", "type": "string" }, "cohort_policy": { "additionalProperties": true, "title": "Minimums and suppression rules; may inherit from program (JSON)", "type": "object" }, "composition_group": { "title": "Groups related definitions for privacy-budget composition", "type": "string" }, "contribution_bounds": { "additionalProperties": true, "title": "Min / max / clipping norms / per-participant caps (JSON)", "type": "object" }, "datasheet_template_ref": { "title": "Required for benchmark exports and model artifacts", "type": "string" }, "definition_api_name": { "title": "Stable slug within program", "type": "string" }, "delta_per_run": { "format": "decimal", "title": "Required for approximate DP mechanisms", "type": "string" }, "dpia_reference": { "title": "Required when program or definition is high-risk", "type": "string" }, "epsilon_per_run": { "format": "decimal", "title": "Required if DP applies", "type": "string" }, "forbidden_field_classes": { "items": { "type": "string" }, "title": "Defaults applied if empty", "type": "array" }, "input_field_allowlist": { "items": { "type": "string" }, "title": "Fully qualified field paths or named derived features", "type": "array" }, "input_object_types": { "items": { "type": "string" }, "title": "Aerandil object types eligible for local reads", "type": "array" }, "local_code_digest": { "title": "Required when local_code_reference is set", "type": "string" }, "local_code_reference": { "title": "Optional code package / container / runner ref", "type": "string" }, "local_execution_requirements": { "additionalProperties": true, "title": "Runner version, memory / timeout bounds, offline mode, network policy (JSON)", "type": "object" }, "local_feature_contract": { "additionalProperties": true, "title": "Bounded schema for local features and aggregate vectors (JSON)", "type": "object" }, "minimum_local_runner_version": { "title": "Optional per-definition hard floor; effective floor is max of program-pin and this value (semver)", "type": "string" }, "model_card_template_ref": { "title": "Required for model artifacts", "type": "string" }, "objective": { "title": "What question the run answers", "type": "string" }, "output_review_required": { "title": "True by default for cross-tenant and model outputs", "type": "boolean" }, "output_schema": { "additionalProperties": true, "title": "Bounded output shape (JSON)", "type": "object" }, "privacy_mechanisms": { "items": { "enum": [ "cohort_threshold", "contribution_bounding", "differential_privacy", "secure_aggregation", "secure_multiparty_computation", "homomorphic_encryption", "private_set_intersection", "trusted_execution_environment", "manual_statistical_disclosure_control", "none_internal_portfolio_only" ], "type": "string" }, "title": "Required; at least cohort_threshold for cross-tenant outputs", "type": "array" }, "publish_status": { "enum": [ "draft", "reviewing", "approved", "deprecated", "revoked" ], "title": "draft (default) or reviewing", "type": "string" }, "recommended_local_runner_version": { "title": "Optional per-definition soft baseline; effective baseline is max of program-pin and this value (semver)", "type": "string" }, "threat_model_ref": { "title": "Required for cross-tenant programs", "type": "string" }, "version": { "title": "Semver-like", "type": "string" }, "weighting_method": { "enum": [ "unweighted", "room_nights", "available_rooms", "eligible_events", "revenue", "reviewed_custom" ], "title": "Weighting method", "type": "string" } }, "required": [ "definition_api_name", "version", "analysis_kind", "objective", "input_object_types", "input_field_allowlist", "forbidden_field_classes", "local_feature_contract", "local_execution_requirements", "algorithm_family", "aggregation_method", "weighting_method", "contribution_bounds", "privacy_mechanisms", "cohort_policy", "output_schema", "output_review_required" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_intelligence_program" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.federated_program_has_definition" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.federated_analysis_definition" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.publish_federated_analysis_definition:apply" ] } ], "summary": "Publish federated analysis definition", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.publish_federated_analysis_definition/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_publish_federated_analysis_definition` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.publish_federated_analysis_definition:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_publish_federated_analysis_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "aggregation_method": { "enum": [ "plain_aggregate_reviewed", "secure_sum", "noisy_count", "noisy_sum", "noisy_mean", "noisy_histogram", "noisy_quantile", "trimmed_mean", "weighted_average", "fedavg", "external_clean_room", "reviewed_custom" ], "title": "Aggregation method", "type": "string" }, "algorithm_family": { "enum": [ "secure_sum", "count_rate", "histogram", "quantile", "calibration_curve", "outcome_decay", "fedavg", "fedxgb", "reviewed_custom" ], "title": "Algorithm family", "type": "string" }, "analysis_kind": { "enum": [ "federated_analytics", "federated_learning", "private_set_intersection", "clean_room_query", "benchmark_export" ], "title": "Analysis kind", "type": "string" }, "cohort_policy": { "additionalProperties": true, "title": "Minimums and suppression rules; may inherit from program (JSON)", "type": "object" }, "composition_group": { "title": "Groups related definitions for privacy-budget composition", "type": "string" }, "contribution_bounds": { "additionalProperties": true, "title": "Min / max / clipping norms / per-participant caps (JSON)", "type": "object" }, "datasheet_template_ref": { "title": "Required for benchmark exports and model artifacts", "type": "string" }, "definition_api_name": { "title": "Stable slug within program", "type": "string" }, "delta_per_run": { "format": "decimal", "title": "Required for approximate DP mechanisms", "type": "string" }, "dpia_reference": { "title": "Required when program or definition is high-risk", "type": "string" }, "epsilon_per_run": { "format": "decimal", "title": "Required if DP applies", "type": "string" }, "forbidden_field_classes": { "items": { "type": "string" }, "title": "Defaults applied if empty", "type": "array" }, "input_field_allowlist": { "items": { "type": "string" }, "title": "Fully qualified field paths or named derived features", "type": "array" }, "input_object_types": { "items": { "type": "string" }, "title": "Aerandil object types eligible for local reads", "type": "array" }, "local_code_digest": { "title": "Required when local_code_reference is set", "type": "string" }, "local_code_reference": { "title": "Optional code package / container / runner ref", "type": "string" }, "local_execution_requirements": { "additionalProperties": true, "title": "Runner version, memory / timeout bounds, offline mode, network policy (JSON)", "type": "object" }, "local_feature_contract": { "additionalProperties": true, "title": "Bounded schema for local features and aggregate vectors (JSON)", "type": "object" }, "minimum_local_runner_version": { "title": "Optional per-definition hard floor; effective floor is max of program-pin and this value (semver)", "type": "string" }, "model_card_template_ref": { "title": "Required for model artifacts", "type": "string" }, "objective": { "title": "What question the run answers", "type": "string" }, "output_review_required": { "title": "True by default for cross-tenant and model outputs", "type": "boolean" }, "output_schema": { "additionalProperties": true, "title": "Bounded output shape (JSON)", "type": "object" }, "privacy_mechanisms": { "items": { "enum": [ "cohort_threshold", "contribution_bounding", "differential_privacy", "secure_aggregation", "secure_multiparty_computation", "homomorphic_encryption", "private_set_intersection", "trusted_execution_environment", "manual_statistical_disclosure_control", "none_internal_portfolio_only" ], "type": "string" }, "title": "Required; at least cohort_threshold for cross-tenant outputs", "type": "array" }, "publish_status": { "enum": [ "draft", "reviewing", "approved", "deprecated", "revoked" ], "title": "draft (default) or reviewing", "type": "string" }, "recommended_local_runner_version": { "title": "Optional per-definition soft baseline; effective baseline is max of program-pin and this value (semver)", "type": "string" }, "threat_model_ref": { "title": "Required for cross-tenant programs", "type": "string" }, "version": { "title": "Semver-like", "type": "string" }, "weighting_method": { "enum": [ "unweighted", "room_nights", "available_rooms", "eligible_events", "revenue", "reviewed_custom" ], "title": "Weighting method", "type": "string" } }, "required": [ "definition_api_name", "version", "analysis_kind", "objective", "input_object_types", "input_field_allowlist", "forbidden_field_classes", "local_feature_contract", "local_execution_requirements", "algorithm_family", "aggregation_method", "weighting_method", "contribution_bounds", "privacy_mechanisms", "cohort_policy", "output_schema", "output_review_required" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_intelligence_program" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.federated_program_has_definition" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.federated_analysis_definition" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Publish federated analysis definition (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.publish_federated_analysis_definition/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_publish_federated_analysis_definition`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_publish_federated_analysis_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "aggregation_method": { "enum": [ "plain_aggregate_reviewed", "secure_sum", "noisy_count", "noisy_sum", "noisy_mean", "noisy_histogram", "noisy_quantile", "trimmed_mean", "weighted_average", "fedavg", "external_clean_room", "reviewed_custom" ], "title": "Aggregation method", "type": "string" }, "algorithm_family": { "enum": [ "secure_sum", "count_rate", "histogram", "quantile", "calibration_curve", "outcome_decay", "fedavg", "fedxgb", "reviewed_custom" ], "title": "Algorithm family", "type": "string" }, "analysis_kind": { "enum": [ "federated_analytics", "federated_learning", "private_set_intersection", "clean_room_query", "benchmark_export" ], "title": "Analysis kind", "type": "string" }, "cohort_policy": { "additionalProperties": true, "title": "Minimums and suppression rules; may inherit from program (JSON)", "type": "object" }, "composition_group": { "title": "Groups related definitions for privacy-budget composition", "type": "string" }, "contribution_bounds": { "additionalProperties": true, "title": "Min / max / clipping norms / per-participant caps (JSON)", "type": "object" }, "datasheet_template_ref": { "title": "Required for benchmark exports and model artifacts", "type": "string" }, "definition_api_name": { "title": "Stable slug within program", "type": "string" }, "delta_per_run": { "format": "decimal", "title": "Required for approximate DP mechanisms", "type": "string" }, "dpia_reference": { "title": "Required when program or definition is high-risk", "type": "string" }, "epsilon_per_run": { "format": "decimal", "title": "Required if DP applies", "type": "string" }, "forbidden_field_classes": { "items": { "type": "string" }, "title": "Defaults applied if empty", "type": "array" }, "input_field_allowlist": { "items": { "type": "string" }, "title": "Fully qualified field paths or named derived features", "type": "array" }, "input_object_types": { "items": { "type": "string" }, "title": "Aerandil object types eligible for local reads", "type": "array" }, "local_code_digest": { "title": "Required when local_code_reference is set", "type": "string" }, "local_code_reference": { "title": "Optional code package / container / runner ref", "type": "string" }, "local_execution_requirements": { "additionalProperties": true, "title": "Runner version, memory / timeout bounds, offline mode, network policy (JSON)", "type": "object" }, "local_feature_contract": { "additionalProperties": true, "title": "Bounded schema for local features and aggregate vectors (JSON)", "type": "object" }, "minimum_local_runner_version": { "title": "Optional per-definition hard floor; effective floor is max of program-pin and this value (semver)", "type": "string" }, "model_card_template_ref": { "title": "Required for model artifacts", "type": "string" }, "objective": { "title": "What question the run answers", "type": "string" }, "output_review_required": { "title": "True by default for cross-tenant and model outputs", "type": "boolean" }, "output_schema": { "additionalProperties": true, "title": "Bounded output shape (JSON)", "type": "object" }, "privacy_mechanisms": { "items": { "enum": [ "cohort_threshold", "contribution_bounding", "differential_privacy", "secure_aggregation", "secure_multiparty_computation", "homomorphic_encryption", "private_set_intersection", "trusted_execution_environment", "manual_statistical_disclosure_control", "none_internal_portfolio_only" ], "type": "string" }, "title": "Required; at least cohort_threshold for cross-tenant outputs", "type": "array" }, "publish_status": { "enum": [ "draft", "reviewing", "approved", "deprecated", "revoked" ], "title": "draft (default) or reviewing", "type": "string" }, "recommended_local_runner_version": { "title": "Optional per-definition soft baseline; effective baseline is max of program-pin and this value (semver)", "type": "string" }, "threat_model_ref": { "title": "Required for cross-tenant programs", "type": "string" }, "version": { "title": "Semver-like", "type": "string" }, "weighting_method": { "enum": [ "unweighted", "room_nights", "available_rooms", "eligible_events", "revenue", "reviewed_custom" ], "title": "Weighting method", "type": "string" } }, "required": [ "definition_api_name", "version", "analysis_kind", "objective", "input_object_types", "input_field_allowlist", "forbidden_field_classes", "local_feature_contract", "local_execution_requirements", "algorithm_family", "aggregation_method", "weighting_method", "contribution_bounds", "privacy_mechanisms", "cohort_policy", "output_schema", "output_review_required" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_intelligence_program" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Publish federated analysis definition (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.publish_federated_analysis_definition/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_publish_federated_analysis_definition` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.publish_federated_analysis_definition:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_publish_federated_analysis_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "aggregation_method": { "enum": [ "plain_aggregate_reviewed", "secure_sum", "noisy_count", "noisy_sum", "noisy_mean", "noisy_histogram", "noisy_quantile", "trimmed_mean", "weighted_average", "fedavg", "external_clean_room", "reviewed_custom" ], "title": "Aggregation method", "type": "string" }, "algorithm_family": { "enum": [ "secure_sum", "count_rate", "histogram", "quantile", "calibration_curve", "outcome_decay", "fedavg", "fedxgb", "reviewed_custom" ], "title": "Algorithm family", "type": "string" }, "analysis_kind": { "enum": [ "federated_analytics", "federated_learning", "private_set_intersection", "clean_room_query", "benchmark_export" ], "title": "Analysis kind", "type": "string" }, "cohort_policy": { "additionalProperties": true, "title": "Minimums and suppression rules; may inherit from program (JSON)", "type": "object" }, "composition_group": { "title": "Groups related definitions for privacy-budget composition", "type": "string" }, "contribution_bounds": { "additionalProperties": true, "title": "Min / max / clipping norms / per-participant caps (JSON)", "type": "object" }, "datasheet_template_ref": { "title": "Required for benchmark exports and model artifacts", "type": "string" }, "definition_api_name": { "title": "Stable slug within program", "type": "string" }, "delta_per_run": { "format": "decimal", "title": "Required for approximate DP mechanisms", "type": "string" }, "dpia_reference": { "title": "Required when program or definition is high-risk", "type": "string" }, "epsilon_per_run": { "format": "decimal", "title": "Required if DP applies", "type": "string" }, "forbidden_field_classes": { "items": { "type": "string" }, "title": "Defaults applied if empty", "type": "array" }, "input_field_allowlist": { "items": { "type": "string" }, "title": "Fully qualified field paths or named derived features", "type": "array" }, "input_object_types": { "items": { "type": "string" }, "title": "Aerandil object types eligible for local reads", "type": "array" }, "local_code_digest": { "title": "Required when local_code_reference is set", "type": "string" }, "local_code_reference": { "title": "Optional code package / container / runner ref", "type": "string" }, "local_execution_requirements": { "additionalProperties": true, "title": "Runner version, memory / timeout bounds, offline mode, network policy (JSON)", "type": "object" }, "local_feature_contract": { "additionalProperties": true, "title": "Bounded schema for local features and aggregate vectors (JSON)", "type": "object" }, "minimum_local_runner_version": { "title": "Optional per-definition hard floor; effective floor is max of program-pin and this value (semver)", "type": "string" }, "model_card_template_ref": { "title": "Required for model artifacts", "type": "string" }, "objective": { "title": "What question the run answers", "type": "string" }, "output_review_required": { "title": "True by default for cross-tenant and model outputs", "type": "boolean" }, "output_schema": { "additionalProperties": true, "title": "Bounded output shape (JSON)", "type": "object" }, "privacy_mechanisms": { "items": { "enum": [ "cohort_threshold", "contribution_bounding", "differential_privacy", "secure_aggregation", "secure_multiparty_computation", "homomorphic_encryption", "private_set_intersection", "trusted_execution_environment", "manual_statistical_disclosure_control", "none_internal_portfolio_only" ], "type": "string" }, "title": "Required; at least cohort_threshold for cross-tenant outputs", "type": "array" }, "publish_status": { "enum": [ "draft", "reviewing", "approved", "deprecated", "revoked" ], "title": "draft (default) or reviewing", "type": "string" }, "recommended_local_runner_version": { "title": "Optional per-definition soft baseline; effective baseline is max of program-pin and this value (semver)", "type": "string" }, "threat_model_ref": { "title": "Required for cross-tenant programs", "type": "string" }, "version": { "title": "Semver-like", "type": "string" }, "weighting_method": { "enum": [ "unweighted", "room_nights", "available_rooms", "eligible_events", "revenue", "reviewed_custom" ], "title": "Weighting method", "type": "string" } }, "required": [ "definition_api_name", "version", "analysis_kind", "objective", "input_object_types", "input_field_allowlist", "forbidden_field_classes", "local_feature_contract", "local_execution_requirements", "algorithm_family", "aggregation_method", "weighting_method", "contribution_bounds", "privacy_mechanisms", "cohort_policy", "output_schema", "output_review_required" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_intelligence_program" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Publish federated analysis definition (rollup delta)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.publish_federated_output/apply": { "post": { "description": "Publish a reviewed output. Validates run status and output schema, validates review gate completion where required, validates suppression and privacy metadata, sets status to `published`. Validators (commit 5): `output_publish_requires_run_completed_or_output_review`, `output_thresholds_satisfied`, `output_model_artifact_requires_card_and_datasheet`, `output_review_gate_required_when_definition_says_so`, `output_no_named_tenants_in_cross_tenant_output`.\n\nEffects: modify hospitality.federated_output; modify hospitality.federated_run; link hospitality.link.federated_output_reviewed_by_gate.", "operationId": "apply_hospitality_action_publish_federated_output", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "applicability_statement": { "title": "What the output can and cannot support", "type": "string" }, "artifact_hash": { "title": "Required when artifact_reference is set", "type": "string" }, "artifact_reference": { "title": "Model artifact / report / card if stored externally", "type": "string" }, "cohort_summary": { "additionalProperties": true, "title": "Buckets; not named participants unless internal portfolio (JSON)", "type": "object" }, "confidence_intervals": { "title": "Required where output is statistical (JSON)" }, "datasheet_reference": { "title": "Required for model artifacts and benchmark exports", "type": "string" }, "downstream_use_restrictions": { "title": "Required", "type": "string" }, "expires_at": { "format": "date-time", "title": "Required for model artifacts unless waived", "type": "string" }, "metric_values": { "title": "Bounded aggregate values (JSON)" }, "model_card_reference": { "title": "Required for model artifacts and signal packages", "type": "string" }, "noise_parameters": { "additionalProperties": true, "title": "Bounded mechanism metadata (JSON)", "type": "object" }, "output_kind": { "enum": [ "benchmark_report", "calibration_curve", "aggregate_metric", "model_artifact", "signal_package", "governance_card" ], "title": "Output kind", "type": "string" }, "output_schema_version": { "title": "Required", "type": "string" }, "privacy_budget_spend": { "title": "Committed budget spend (JSON)" }, "privacy_guarantee_summary": { "additionalProperties": true, "title": "Mechanisms, epsilon / delta, thresholds (JSON)", "type": "object" }, "published_to_scope": { "enum": [ "program_owner", "participants", "public_aggregate", "specific_recipients" ], "title": "Output access scope", "type": "string" }, "review_gate_id": { "title": "Required when output review is required", "type": "string" } }, "required": [ "output_kind", "output_schema_version", "cohort_summary", "privacy_guarantee_summary", "privacy_budget_spend", "applicability_statement", "downstream_use_restrictions", "published_to_scope" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_output" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.federated_output_reviewed_by_gate" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.federated_output", "hospitality.federated_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.publish_federated_output:apply" ] } ], "summary": "Publish federated output", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.publish_federated_output/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_publish_federated_output` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.publish_federated_output:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_publish_federated_output", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "applicability_statement": { "title": "What the output can and cannot support", "type": "string" }, "artifact_hash": { "title": "Required when artifact_reference is set", "type": "string" }, "artifact_reference": { "title": "Model artifact / report / card if stored externally", "type": "string" }, "cohort_summary": { "additionalProperties": true, "title": "Buckets; not named participants unless internal portfolio (JSON)", "type": "object" }, "confidence_intervals": { "title": "Required where output is statistical (JSON)" }, "datasheet_reference": { "title": "Required for model artifacts and benchmark exports", "type": "string" }, "downstream_use_restrictions": { "title": "Required", "type": "string" }, "expires_at": { "format": "date-time", "title": "Required for model artifacts unless waived", "type": "string" }, "metric_values": { "title": "Bounded aggregate values (JSON)" }, "model_card_reference": { "title": "Required for model artifacts and signal packages", "type": "string" }, "noise_parameters": { "additionalProperties": true, "title": "Bounded mechanism metadata (JSON)", "type": "object" }, "output_kind": { "enum": [ "benchmark_report", "calibration_curve", "aggregate_metric", "model_artifact", "signal_package", "governance_card" ], "title": "Output kind", "type": "string" }, "output_schema_version": { "title": "Required", "type": "string" }, "privacy_budget_spend": { "title": "Committed budget spend (JSON)" }, "privacy_guarantee_summary": { "additionalProperties": true, "title": "Mechanisms, epsilon / delta, thresholds (JSON)", "type": "object" }, "published_to_scope": { "enum": [ "program_owner", "participants", "public_aggregate", "specific_recipients" ], "title": "Output access scope", "type": "string" }, "review_gate_id": { "title": "Required when output review is required", "type": "string" } }, "required": [ "output_kind", "output_schema_version", "cohort_summary", "privacy_guarantee_summary", "privacy_budget_spend", "applicability_statement", "downstream_use_restrictions", "published_to_scope" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_output" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.federated_output_reviewed_by_gate" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.federated_output", "hospitality.federated_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Publish federated output (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.publish_federated_output/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_publish_federated_output`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_publish_federated_output", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "applicability_statement": { "title": "What the output can and cannot support", "type": "string" }, "artifact_hash": { "title": "Required when artifact_reference is set", "type": "string" }, "artifact_reference": { "title": "Model artifact / report / card if stored externally", "type": "string" }, "cohort_summary": { "additionalProperties": true, "title": "Buckets; not named participants unless internal portfolio (JSON)", "type": "object" }, "confidence_intervals": { "title": "Required where output is statistical (JSON)" }, "datasheet_reference": { "title": "Required for model artifacts and benchmark exports", "type": "string" }, "downstream_use_restrictions": { "title": "Required", "type": "string" }, "expires_at": { "format": "date-time", "title": "Required for model artifacts unless waived", "type": "string" }, "metric_values": { "title": "Bounded aggregate values (JSON)" }, "model_card_reference": { "title": "Required for model artifacts and signal packages", "type": "string" }, "noise_parameters": { "additionalProperties": true, "title": "Bounded mechanism metadata (JSON)", "type": "object" }, "output_kind": { "enum": [ "benchmark_report", "calibration_curve", "aggregate_metric", "model_artifact", "signal_package", "governance_card" ], "title": "Output kind", "type": "string" }, "output_schema_version": { "title": "Required", "type": "string" }, "privacy_budget_spend": { "title": "Committed budget spend (JSON)" }, "privacy_guarantee_summary": { "additionalProperties": true, "title": "Mechanisms, epsilon / delta, thresholds (JSON)", "type": "object" }, "published_to_scope": { "enum": [ "program_owner", "participants", "public_aggregate", "specific_recipients" ], "title": "Output access scope", "type": "string" }, "review_gate_id": { "title": "Required when output review is required", "type": "string" } }, "required": [ "output_kind", "output_schema_version", "cohort_summary", "privacy_guarantee_summary", "privacy_budget_spend", "applicability_statement", "downstream_use_restrictions", "published_to_scope" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_output" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Publish federated output (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.publish_federated_output/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_publish_federated_output` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.publish_federated_output:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_publish_federated_output", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "applicability_statement": { "title": "What the output can and cannot support", "type": "string" }, "artifact_hash": { "title": "Required when artifact_reference is set", "type": "string" }, "artifact_reference": { "title": "Model artifact / report / card if stored externally", "type": "string" }, "cohort_summary": { "additionalProperties": true, "title": "Buckets; not named participants unless internal portfolio (JSON)", "type": "object" }, "confidence_intervals": { "title": "Required where output is statistical (JSON)" }, "datasheet_reference": { "title": "Required for model artifacts and benchmark exports", "type": "string" }, "downstream_use_restrictions": { "title": "Required", "type": "string" }, "expires_at": { "format": "date-time", "title": "Required for model artifacts unless waived", "type": "string" }, "metric_values": { "title": "Bounded aggregate values (JSON)" }, "model_card_reference": { "title": "Required for model artifacts and signal packages", "type": "string" }, "noise_parameters": { "additionalProperties": true, "title": "Bounded mechanism metadata (JSON)", "type": "object" }, "output_kind": { "enum": [ "benchmark_report", "calibration_curve", "aggregate_metric", "model_artifact", "signal_package", "governance_card" ], "title": "Output kind", "type": "string" }, "output_schema_version": { "title": "Required", "type": "string" }, "privacy_budget_spend": { "title": "Committed budget spend (JSON)" }, "privacy_guarantee_summary": { "additionalProperties": true, "title": "Mechanisms, epsilon / delta, thresholds (JSON)", "type": "object" }, "published_to_scope": { "enum": [ "program_owner", "participants", "public_aggregate", "specific_recipients" ], "title": "Output access scope", "type": "string" }, "review_gate_id": { "title": "Required when output review is required", "type": "string" } }, "required": [ "output_kind", "output_schema_version", "cohort_summary", "privacy_guarantee_summary", "privacy_budget_spend", "applicability_statement", "downstream_use_restrictions", "published_to_scope" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_output" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Publish federated output (rollup delta)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.publish_federated_program/apply": { "post": { "description": "Create or activate a federated intelligence program. Cross-tenant programs require `default_min_tenants >= 3`, `default_min_properties >= 3`, and `default_max_contributor_share`; high-risk programs require a DPIA reference. Validators (commit 5): `program_cross_tenant_minimums`, `program_high_risk_requires_dpia_review`, `program_dpa_required_for_cross_tenant`, `program_none_threshold_only_internal_portfolio_only`.\n\nEffects: create hospitality.federated_intelligence_program.", "operationId": "apply_hospitality_action_publish_federated_program", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allowed_analysis_kinds": { "items": { "enum": [ "federated_analytics", "federated_learning", "private_set_intersection", "clean_room_query", "benchmark_export" ], "type": "string" }, "title": "Analytics first; learning requires review", "type": "array" }, "allowed_output_kinds": { "items": { "enum": [ "benchmark_report", "calibration_curve", "aggregate_metric", "model_artifact", "signal_package", "governance_card" ], "type": "string" }, "title": "Allowed output kinds", "type": "array" }, "api_name": { "title": "Stable slug; unique within owner scope", "type": "string" }, "coordinator_kind": { "enum": [ "aerandil", "tenant", "consortium", "third_party_clean_room" ], "title": "aerandil / tenant / consortium / third_party_clean_room", "type": "string" }, "coordinator_reference": { "title": "Optional system or contract reference", "type": "string" }, "default_delta": { "format": "decimal", "title": "Required when default_epsilon set and mechanism needs delta", "type": "string" }, "default_epsilon": { "format": "decimal", "title": "Program-level default for DP definitions", "type": "string" }, "default_max_contributor_share": { "format": "decimal", "title": "Decimal in [0,1]", "type": "string" }, "default_min_properties": { "title": "Hard minimum", "type": "integer" }, "default_min_subjects": { "title": "Required when output can be person-affecting", "type": "integer" }, "default_min_tenants": { "title": "Hard minimum (>= 3 for cross_tenant_network)", "type": "integer" }, "default_privacy_mechanisms": { "items": { "enum": [ "cohort_threshold", "contribution_bounding", "differential_privacy", "secure_aggregation", "secure_multiparty_computation", "homomorphic_encryption", "private_set_intersection", "trusted_execution_environment", "manual_statistical_disclosure_control", "none_internal_portfolio_only" ], "type": "string" }, "title": "Default privacy mechanisms applied per definition", "type": "array" }, "description": { "title": "Bounded operator-facing summary", "type": "string" }, "display_name": { "title": "Human-readable name", "type": "string" }, "downstream_use_policy": { "title": "Allowed uses for outputs", "type": "string" }, "dpa_reference": { "title": "Required for cross-tenant unless waived", "type": "string" }, "dpia_reference": { "title": "Required for high-risk or person-affecting programs", "type": "string" }, "effective_from": { "format": "date-time", "title": "Optional", "type": "string" }, "effective_to": { "format": "date-time", "title": "Optional", "type": "string" }, "governance_tier": { "enum": [ "internal_portfolio", "cross_tenant_network", "consortium_governed", "high_risk_review" ], "title": "Governance tier", "type": "string" }, "legal_basis_summary": { "title": "Bounded summary", "type": "string" }, "minimum_local_runner_version": { "title": "Optional program-wide hard floor for local-runner semver; contributions below this are rejected at action time", "type": "string" }, "owner_ref": { "title": "Consortium / operator governance reference when owner is not single-tenant", "type": "string" }, "owner_scope": { "enum": [ "tenant", "consortium", "aerandil_managed" ], "title": "tenant / consortium / aerandil_managed", "type": "string" }, "participant_benefit_policy": { "title": "What participants receive in return", "type": "string" }, "privacy_budget_period": { "enum": [ "run", "day", "month", "quarter", "year", "lifetime" ], "title": "Default budget period", "type": "string" }, "publish_status": { "enum": [ "draft", "reviewing", "active", "paused", "deprecated", "retired" ], "title": "draft (default) or active", "type": "string" }, "purpose": { "enum": [ "rate_recommendation_calibration", "fraud_signal_calibration", "service_recovery_benchmark", "agent_quality_benchmark", "payment_review_benchmark", "outlet_profitability_benchmark", "energy_water_waste_benchmark", "operations_research", "consortium_standardization", "reviewed_custom" ], "title": "Drives legal / review expectations", "type": "string" }, "recommended_local_runner_version": { "title": "Optional program-wide soft baseline for local-runner semver; contributions below this emit `contribution_runner_version_outdated_warns`", "type": "string" }, "review_gate_policy": { "title": "Which definitions / outputs require approval gates (JSON)" } }, "required": [ "api_name", "display_name", "owner_scope", "purpose", "governance_tier", "allowed_analysis_kinds", "allowed_output_kinds", "default_min_tenants", "default_min_properties", "default_max_contributor_share", "default_privacy_mechanisms", "privacy_budget_period", "coordinator_kind", "review_gate_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.federated_intelligence_program" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.publish_federated_program:apply" ] } ], "summary": "Publish federated intelligence program", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.publish_federated_program/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_publish_federated_program` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.publish_federated_program:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_publish_federated_program", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allowed_analysis_kinds": { "items": { "enum": [ "federated_analytics", "federated_learning", "private_set_intersection", "clean_room_query", "benchmark_export" ], "type": "string" }, "title": "Analytics first; learning requires review", "type": "array" }, "allowed_output_kinds": { "items": { "enum": [ "benchmark_report", "calibration_curve", "aggregate_metric", "model_artifact", "signal_package", "governance_card" ], "type": "string" }, "title": "Allowed output kinds", "type": "array" }, "api_name": { "title": "Stable slug; unique within owner scope", "type": "string" }, "coordinator_kind": { "enum": [ "aerandil", "tenant", "consortium", "third_party_clean_room" ], "title": "aerandil / tenant / consortium / third_party_clean_room", "type": "string" }, "coordinator_reference": { "title": "Optional system or contract reference", "type": "string" }, "default_delta": { "format": "decimal", "title": "Required when default_epsilon set and mechanism needs delta", "type": "string" }, "default_epsilon": { "format": "decimal", "title": "Program-level default for DP definitions", "type": "string" }, "default_max_contributor_share": { "format": "decimal", "title": "Decimal in [0,1]", "type": "string" }, "default_min_properties": { "title": "Hard minimum", "type": "integer" }, "default_min_subjects": { "title": "Required when output can be person-affecting", "type": "integer" }, "default_min_tenants": { "title": "Hard minimum (>= 3 for cross_tenant_network)", "type": "integer" }, "default_privacy_mechanisms": { "items": { "enum": [ "cohort_threshold", "contribution_bounding", "differential_privacy", "secure_aggregation", "secure_multiparty_computation", "homomorphic_encryption", "private_set_intersection", "trusted_execution_environment", "manual_statistical_disclosure_control", "none_internal_portfolio_only" ], "type": "string" }, "title": "Default privacy mechanisms applied per definition", "type": "array" }, "description": { "title": "Bounded operator-facing summary", "type": "string" }, "display_name": { "title": "Human-readable name", "type": "string" }, "downstream_use_policy": { "title": "Allowed uses for outputs", "type": "string" }, "dpa_reference": { "title": "Required for cross-tenant unless waived", "type": "string" }, "dpia_reference": { "title": "Required for high-risk or person-affecting programs", "type": "string" }, "effective_from": { "format": "date-time", "title": "Optional", "type": "string" }, "effective_to": { "format": "date-time", "title": "Optional", "type": "string" }, "governance_tier": { "enum": [ "internal_portfolio", "cross_tenant_network", "consortium_governed", "high_risk_review" ], "title": "Governance tier", "type": "string" }, "legal_basis_summary": { "title": "Bounded summary", "type": "string" }, "minimum_local_runner_version": { "title": "Optional program-wide hard floor for local-runner semver; contributions below this are rejected at action time", "type": "string" }, "owner_ref": { "title": "Consortium / operator governance reference when owner is not single-tenant", "type": "string" }, "owner_scope": { "enum": [ "tenant", "consortium", "aerandil_managed" ], "title": "tenant / consortium / aerandil_managed", "type": "string" }, "participant_benefit_policy": { "title": "What participants receive in return", "type": "string" }, "privacy_budget_period": { "enum": [ "run", "day", "month", "quarter", "year", "lifetime" ], "title": "Default budget period", "type": "string" }, "publish_status": { "enum": [ "draft", "reviewing", "active", "paused", "deprecated", "retired" ], "title": "draft (default) or active", "type": "string" }, "purpose": { "enum": [ "rate_recommendation_calibration", "fraud_signal_calibration", "service_recovery_benchmark", "agent_quality_benchmark", "payment_review_benchmark", "outlet_profitability_benchmark", "energy_water_waste_benchmark", "operations_research", "consortium_standardization", "reviewed_custom" ], "title": "Drives legal / review expectations", "type": "string" }, "recommended_local_runner_version": { "title": "Optional program-wide soft baseline for local-runner semver; contributions below this emit `contribution_runner_version_outdated_warns`", "type": "string" }, "review_gate_policy": { "title": "Which definitions / outputs require approval gates (JSON)" } }, "required": [ "api_name", "display_name", "owner_scope", "purpose", "governance_tier", "allowed_analysis_kinds", "allowed_output_kinds", "default_min_tenants", "default_min_properties", "default_max_contributor_share", "default_privacy_mechanisms", "privacy_budget_period", "coordinator_kind", "review_gate_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.federated_intelligence_program" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Publish federated intelligence program (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.publish_federated_program/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_publish_federated_program`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_publish_federated_program", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allowed_analysis_kinds": { "items": { "enum": [ "federated_analytics", "federated_learning", "private_set_intersection", "clean_room_query", "benchmark_export" ], "type": "string" }, "title": "Analytics first; learning requires review", "type": "array" }, "allowed_output_kinds": { "items": { "enum": [ "benchmark_report", "calibration_curve", "aggregate_metric", "model_artifact", "signal_package", "governance_card" ], "type": "string" }, "title": "Allowed output kinds", "type": "array" }, "api_name": { "title": "Stable slug; unique within owner scope", "type": "string" }, "coordinator_kind": { "enum": [ "aerandil", "tenant", "consortium", "third_party_clean_room" ], "title": "aerandil / tenant / consortium / third_party_clean_room", "type": "string" }, "coordinator_reference": { "title": "Optional system or contract reference", "type": "string" }, "default_delta": { "format": "decimal", "title": "Required when default_epsilon set and mechanism needs delta", "type": "string" }, "default_epsilon": { "format": "decimal", "title": "Program-level default for DP definitions", "type": "string" }, "default_max_contributor_share": { "format": "decimal", "title": "Decimal in [0,1]", "type": "string" }, "default_min_properties": { "title": "Hard minimum", "type": "integer" }, "default_min_subjects": { "title": "Required when output can be person-affecting", "type": "integer" }, "default_min_tenants": { "title": "Hard minimum (>= 3 for cross_tenant_network)", "type": "integer" }, "default_privacy_mechanisms": { "items": { "enum": [ "cohort_threshold", "contribution_bounding", "differential_privacy", "secure_aggregation", "secure_multiparty_computation", "homomorphic_encryption", "private_set_intersection", "trusted_execution_environment", "manual_statistical_disclosure_control", "none_internal_portfolio_only" ], "type": "string" }, "title": "Default privacy mechanisms applied per definition", "type": "array" }, "description": { "title": "Bounded operator-facing summary", "type": "string" }, "display_name": { "title": "Human-readable name", "type": "string" }, "downstream_use_policy": { "title": "Allowed uses for outputs", "type": "string" }, "dpa_reference": { "title": "Required for cross-tenant unless waived", "type": "string" }, "dpia_reference": { "title": "Required for high-risk or person-affecting programs", "type": "string" }, "effective_from": { "format": "date-time", "title": "Optional", "type": "string" }, "effective_to": { "format": "date-time", "title": "Optional", "type": "string" }, "governance_tier": { "enum": [ "internal_portfolio", "cross_tenant_network", "consortium_governed", "high_risk_review" ], "title": "Governance tier", "type": "string" }, "legal_basis_summary": { "title": "Bounded summary", "type": "string" }, "minimum_local_runner_version": { "title": "Optional program-wide hard floor for local-runner semver; contributions below this are rejected at action time", "type": "string" }, "owner_ref": { "title": "Consortium / operator governance reference when owner is not single-tenant", "type": "string" }, "owner_scope": { "enum": [ "tenant", "consortium", "aerandil_managed" ], "title": "tenant / consortium / aerandil_managed", "type": "string" }, "participant_benefit_policy": { "title": "What participants receive in return", "type": "string" }, "privacy_budget_period": { "enum": [ "run", "day", "month", "quarter", "year", "lifetime" ], "title": "Default budget period", "type": "string" }, "publish_status": { "enum": [ "draft", "reviewing", "active", "paused", "deprecated", "retired" ], "title": "draft (default) or active", "type": "string" }, "purpose": { "enum": [ "rate_recommendation_calibration", "fraud_signal_calibration", "service_recovery_benchmark", "agent_quality_benchmark", "payment_review_benchmark", "outlet_profitability_benchmark", "energy_water_waste_benchmark", "operations_research", "consortium_standardization", "reviewed_custom" ], "title": "Drives legal / review expectations", "type": "string" }, "recommended_local_runner_version": { "title": "Optional program-wide soft baseline for local-runner semver; contributions below this emit `contribution_runner_version_outdated_warns`", "type": "string" }, "review_gate_policy": { "title": "Which definitions / outputs require approval gates (JSON)" } }, "required": [ "api_name", "display_name", "owner_scope", "purpose", "governance_tier", "allowed_analysis_kinds", "allowed_output_kinds", "default_min_tenants", "default_min_properties", "default_max_contributor_share", "default_privacy_mechanisms", "privacy_budget_period", "coordinator_kind", "review_gate_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Publish federated intelligence program (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.publish_federated_program/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_publish_federated_program` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.publish_federated_program:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_publish_federated_program", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allowed_analysis_kinds": { "items": { "enum": [ "federated_analytics", "federated_learning", "private_set_intersection", "clean_room_query", "benchmark_export" ], "type": "string" }, "title": "Analytics first; learning requires review", "type": "array" }, "allowed_output_kinds": { "items": { "enum": [ "benchmark_report", "calibration_curve", "aggregate_metric", "model_artifact", "signal_package", "governance_card" ], "type": "string" }, "title": "Allowed output kinds", "type": "array" }, "api_name": { "title": "Stable slug; unique within owner scope", "type": "string" }, "coordinator_kind": { "enum": [ "aerandil", "tenant", "consortium", "third_party_clean_room" ], "title": "aerandil / tenant / consortium / third_party_clean_room", "type": "string" }, "coordinator_reference": { "title": "Optional system or contract reference", "type": "string" }, "default_delta": { "format": "decimal", "title": "Required when default_epsilon set and mechanism needs delta", "type": "string" }, "default_epsilon": { "format": "decimal", "title": "Program-level default for DP definitions", "type": "string" }, "default_max_contributor_share": { "format": "decimal", "title": "Decimal in [0,1]", "type": "string" }, "default_min_properties": { "title": "Hard minimum", "type": "integer" }, "default_min_subjects": { "title": "Required when output can be person-affecting", "type": "integer" }, "default_min_tenants": { "title": "Hard minimum (>= 3 for cross_tenant_network)", "type": "integer" }, "default_privacy_mechanisms": { "items": { "enum": [ "cohort_threshold", "contribution_bounding", "differential_privacy", "secure_aggregation", "secure_multiparty_computation", "homomorphic_encryption", "private_set_intersection", "trusted_execution_environment", "manual_statistical_disclosure_control", "none_internal_portfolio_only" ], "type": "string" }, "title": "Default privacy mechanisms applied per definition", "type": "array" }, "description": { "title": "Bounded operator-facing summary", "type": "string" }, "display_name": { "title": "Human-readable name", "type": "string" }, "downstream_use_policy": { "title": "Allowed uses for outputs", "type": "string" }, "dpa_reference": { "title": "Required for cross-tenant unless waived", "type": "string" }, "dpia_reference": { "title": "Required for high-risk or person-affecting programs", "type": "string" }, "effective_from": { "format": "date-time", "title": "Optional", "type": "string" }, "effective_to": { "format": "date-time", "title": "Optional", "type": "string" }, "governance_tier": { "enum": [ "internal_portfolio", "cross_tenant_network", "consortium_governed", "high_risk_review" ], "title": "Governance tier", "type": "string" }, "legal_basis_summary": { "title": "Bounded summary", "type": "string" }, "minimum_local_runner_version": { "title": "Optional program-wide hard floor for local-runner semver; contributions below this are rejected at action time", "type": "string" }, "owner_ref": { "title": "Consortium / operator governance reference when owner is not single-tenant", "type": "string" }, "owner_scope": { "enum": [ "tenant", "consortium", "aerandil_managed" ], "title": "tenant / consortium / aerandil_managed", "type": "string" }, "participant_benefit_policy": { "title": "What participants receive in return", "type": "string" }, "privacy_budget_period": { "enum": [ "run", "day", "month", "quarter", "year", "lifetime" ], "title": "Default budget period", "type": "string" }, "publish_status": { "enum": [ "draft", "reviewing", "active", "paused", "deprecated", "retired" ], "title": "draft (default) or active", "type": "string" }, "purpose": { "enum": [ "rate_recommendation_calibration", "fraud_signal_calibration", "service_recovery_benchmark", "agent_quality_benchmark", "payment_review_benchmark", "outlet_profitability_benchmark", "energy_water_waste_benchmark", "operations_research", "consortium_standardization", "reviewed_custom" ], "title": "Drives legal / review expectations", "type": "string" }, "recommended_local_runner_version": { "title": "Optional program-wide soft baseline for local-runner semver; contributions below this emit `contribution_runner_version_outdated_warns`", "type": "string" }, "review_gate_policy": { "title": "Which definitions / outputs require approval gates (JSON)" } }, "required": [ "api_name", "display_name", "owner_scope", "purpose", "governance_tier", "allowed_analysis_kinds", "allowed_output_kinds", "default_min_tenants", "default_min_properties", "default_max_contributor_share", "default_privacy_mechanisms", "privacy_budget_period", "coordinator_kind", "review_gate_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Publish federated intelligence program (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.publish_model_version/apply": { "post": { "description": "Register that a new model version has been published (proposal 0026 §4 step 5). Thin lifecycle emitter — the training run itself is out of scope (§6) — that emits `model.version_published` with the model identity, the `training_cohort_id` it was trained from, and the SISA `training_shard_ids`. Paired with `retrain_shard` on the revocation-driven unlearning path: a shard retrain bumps the version, which is published here.", "operationId": "apply_hospitality_action_publish_model_version", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "model_card_uri": { "title": "Opaque pointer to the model card for this version", "type": "string" }, "model_name": { "title": "Model whose new version is published (ApiName form)", "type": "string" }, "model_version": { "title": "The published model version", "type": "integer" }, "run_id": { "title": "MLflow run id (uuid) of the run that produced this version", "type": "string" }, "training_cohort_id": { "title": "The training_cohort id this version was trained from", "type": "string" }, "training_shard_ids": { "items": { "type": "integer" }, "title": "SISA shard ids that composed this version", "type": "array" } }, "required": [ "model_name", "model_version", "run_id", "training_cohort_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.publish_model_version:apply" ] } ], "summary": "Publish model version", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.publish_model_version/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_publish_model_version` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.publish_model_version:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_publish_model_version", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "model_card_uri": { "title": "Opaque pointer to the model card for this version", "type": "string" }, "model_name": { "title": "Model whose new version is published (ApiName form)", "type": "string" }, "model_version": { "title": "The published model version", "type": "integer" }, "run_id": { "title": "MLflow run id (uuid) of the run that produced this version", "type": "string" }, "training_cohort_id": { "title": "The training_cohort id this version was trained from", "type": "string" }, "training_shard_ids": { "items": { "type": "integer" }, "title": "SISA shard ids that composed this version", "type": "array" } }, "required": [ "model_name", "model_version", "run_id", "training_cohort_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Publish model version (dry-run)", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.publish_model_version/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_publish_model_version`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_publish_model_version", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "model_card_uri": { "title": "Opaque pointer to the model card for this version", "type": "string" }, "model_name": { "title": "Model whose new version is published (ApiName form)", "type": "string" }, "model_version": { "title": "The published model version", "type": "integer" }, "run_id": { "title": "MLflow run id (uuid) of the run that produced this version", "type": "string" }, "training_cohort_id": { "title": "The training_cohort id this version was trained from", "type": "string" }, "training_shard_ids": { "items": { "type": "integer" }, "title": "SISA shard ids that composed this version", "type": "array" } }, "required": [ "model_name", "model_version", "run_id", "training_cohort_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Publish model version (dry-run)", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.publish_model_version/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_publish_model_version` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.publish_model_version:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_publish_model_version", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "model_card_uri": { "title": "Opaque pointer to the model card for this version", "type": "string" }, "model_name": { "title": "Model whose new version is published (ApiName form)", "type": "string" }, "model_version": { "title": "The published model version", "type": "integer" }, "run_id": { "title": "MLflow run id (uuid) of the run that produced this version", "type": "string" }, "training_cohort_id": { "title": "The training_cohort id this version was trained from", "type": "string" }, "training_shard_ids": { "items": { "type": "integer" }, "title": "SISA shard ids that composed this version", "type": "array" } }, "required": [ "model_name", "model_version", "run_id", "training_cohort_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Publish model version (rollup delta)", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.publish_workflow_definition/apply": { "post": { "description": "Create a new `workflow_definition` (status `draft` or `active` per `publish_status`) and compute its canonical `definition_hash`. Once active the `step_definitions`, schemas, risk tiers, and policies are immutable — operators publish a new version to change them. Validators (commit 9): step-keys-unique, DAG-acyclic, registered-action/function-names, target-selector-required, mutating-steps-have-idempotency, retry-bounded, subworkflow ref/acyclic/depth, high-risk-gate-required, compensation-declared-for-side-effects.\n\nEffects: create hospitality.workflow_definition.", "operationId": "apply_hospitality_action_publish_workflow_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "changelog_note": { "title": "Human explanation for the version", "type": "string" }, "compensation_policy": { "enum": [ "none", "best_effort", "required_for_side_effects", "manual_only" ], "title": "How the definition handles compensation after failure", "type": "string" }, "default_retry_policy": { "title": "Default retry settings" }, "description": { "title": "Bounded to 2048 characters", "type": "string" }, "high_risk_policy": { "enum": [ "forbid_auto_apply", "require_gate", "allow_with_policy" ], "title": "How the definition treats high `risk_tier` steps", "type": "string" }, "input_schema": { "additionalProperties": true, "title": "JSON-Schema-shaped input contract", "type": "object" }, "output_schema": { "additionalProperties": true, "title": "JSON-Schema-shaped output contract", "type": "object" }, "publish_status": { "enum": [ "draft", "active", "deprecated", "retired" ], "title": "`draft` (default) or `active`", "type": "string" }, "step_definitions": { "title": "Ordered step definitions per §4.1.1 (JSON array; per-entry typed shape enforced by the workflow_definition validators in commit 9)" }, "timeout_policy": { "title": "Run-level timeout / expiry settings" }, "title": { "title": "Human-readable name", "type": "string" }, "trigger_kind": { "enum": [ "manual", "event", "schedule", "webhook", "agent_requested", "api" ], "title": "What kind of caller starts runs of this definition", "type": "string" }, "version": { "title": "Operator-controlled semantic version or date", "type": "string" }, "workflow_key": { "title": "Stable key under the tenant namespace", "type": "string" } }, "required": [ "workflow_key", "version", "title", "trigger_kind", "input_schema", "step_definitions", "compensation_policy", "high_risk_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.workflow_definition" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.publish_workflow_definition:apply" ] } ], "summary": "Publish workflow definition", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.publish_workflow_definition/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_publish_workflow_definition` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.publish_workflow_definition:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_publish_workflow_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "changelog_note": { "title": "Human explanation for the version", "type": "string" }, "compensation_policy": { "enum": [ "none", "best_effort", "required_for_side_effects", "manual_only" ], "title": "How the definition handles compensation after failure", "type": "string" }, "default_retry_policy": { "title": "Default retry settings" }, "description": { "title": "Bounded to 2048 characters", "type": "string" }, "high_risk_policy": { "enum": [ "forbid_auto_apply", "require_gate", "allow_with_policy" ], "title": "How the definition treats high `risk_tier` steps", "type": "string" }, "input_schema": { "additionalProperties": true, "title": "JSON-Schema-shaped input contract", "type": "object" }, "output_schema": { "additionalProperties": true, "title": "JSON-Schema-shaped output contract", "type": "object" }, "publish_status": { "enum": [ "draft", "active", "deprecated", "retired" ], "title": "`draft` (default) or `active`", "type": "string" }, "step_definitions": { "title": "Ordered step definitions per §4.1.1 (JSON array; per-entry typed shape enforced by the workflow_definition validators in commit 9)" }, "timeout_policy": { "title": "Run-level timeout / expiry settings" }, "title": { "title": "Human-readable name", "type": "string" }, "trigger_kind": { "enum": [ "manual", "event", "schedule", "webhook", "agent_requested", "api" ], "title": "What kind of caller starts runs of this definition", "type": "string" }, "version": { "title": "Operator-controlled semantic version or date", "type": "string" }, "workflow_key": { "title": "Stable key under the tenant namespace", "type": "string" } }, "required": [ "workflow_key", "version", "title", "trigger_kind", "input_schema", "step_definitions", "compensation_policy", "high_risk_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.workflow_definition" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Publish workflow definition (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.publish_workflow_definition/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_publish_workflow_definition`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_publish_workflow_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "changelog_note": { "title": "Human explanation for the version", "type": "string" }, "compensation_policy": { "enum": [ "none", "best_effort", "required_for_side_effects", "manual_only" ], "title": "How the definition handles compensation after failure", "type": "string" }, "default_retry_policy": { "title": "Default retry settings" }, "description": { "title": "Bounded to 2048 characters", "type": "string" }, "high_risk_policy": { "enum": [ "forbid_auto_apply", "require_gate", "allow_with_policy" ], "title": "How the definition treats high `risk_tier` steps", "type": "string" }, "input_schema": { "additionalProperties": true, "title": "JSON-Schema-shaped input contract", "type": "object" }, "output_schema": { "additionalProperties": true, "title": "JSON-Schema-shaped output contract", "type": "object" }, "publish_status": { "enum": [ "draft", "active", "deprecated", "retired" ], "title": "`draft` (default) or `active`", "type": "string" }, "step_definitions": { "title": "Ordered step definitions per §4.1.1 (JSON array; per-entry typed shape enforced by the workflow_definition validators in commit 9)" }, "timeout_policy": { "title": "Run-level timeout / expiry settings" }, "title": { "title": "Human-readable name", "type": "string" }, "trigger_kind": { "enum": [ "manual", "event", "schedule", "webhook", "agent_requested", "api" ], "title": "What kind of caller starts runs of this definition", "type": "string" }, "version": { "title": "Operator-controlled semantic version or date", "type": "string" }, "workflow_key": { "title": "Stable key under the tenant namespace", "type": "string" } }, "required": [ "workflow_key", "version", "title", "trigger_kind", "input_schema", "step_definitions", "compensation_policy", "high_risk_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Publish workflow definition (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.publish_workflow_definition/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_publish_workflow_definition` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.publish_workflow_definition:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_publish_workflow_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "changelog_note": { "title": "Human explanation for the version", "type": "string" }, "compensation_policy": { "enum": [ "none", "best_effort", "required_for_side_effects", "manual_only" ], "title": "How the definition handles compensation after failure", "type": "string" }, "default_retry_policy": { "title": "Default retry settings" }, "description": { "title": "Bounded to 2048 characters", "type": "string" }, "high_risk_policy": { "enum": [ "forbid_auto_apply", "require_gate", "allow_with_policy" ], "title": "How the definition treats high `risk_tier` steps", "type": "string" }, "input_schema": { "additionalProperties": true, "title": "JSON-Schema-shaped input contract", "type": "object" }, "output_schema": { "additionalProperties": true, "title": "JSON-Schema-shaped output contract", "type": "object" }, "publish_status": { "enum": [ "draft", "active", "deprecated", "retired" ], "title": "`draft` (default) or `active`", "type": "string" }, "step_definitions": { "title": "Ordered step definitions per §4.1.1 (JSON array; per-entry typed shape enforced by the workflow_definition validators in commit 9)" }, "timeout_policy": { "title": "Run-level timeout / expiry settings" }, "title": { "title": "Human-readable name", "type": "string" }, "trigger_kind": { "enum": [ "manual", "event", "schedule", "webhook", "agent_requested", "api" ], "title": "What kind of caller starts runs of this definition", "type": "string" }, "version": { "title": "Operator-controlled semantic version or date", "type": "string" }, "workflow_key": { "title": "Stable key under the tenant namespace", "type": "string" } }, "required": [ "workflow_key", "version", "title", "trigger_kind", "input_schema", "step_definitions", "compensation_policy", "high_risk_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Publish workflow definition (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.quarantine_federated_output/apply": { "post": { "description": "Remove an unsafe output from normal consumption without deleting history. Sets output status `quarantined`, disables reads except for privileged compliance scopes, optionally pauses related definitions / programs, and notifies participants. Since an output may have been read already, quarantine cannot pretend to erase knowledge — it preserves evidence for audit and incident response (proposal §10.7 / §8.12).\n\nEffects: modify hospitality.federated_output; create hospitality.participant_dispatch_attempt; link hospitality.link.participant_dispatch_for_run.", "operationId": "apply_hospitality_action_quarantine_federated_output", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_at": { "format": "date-time", "title": "Defaults to now()", "type": "string" }, "incident_reference": { "title": "External incident ref", "type": "string" }, "notify_participants": { "title": "Whether to notify participants", "type": "boolean" }, "quarantine_reason": { "title": "Required text reason", "type": "string" } }, "required": [ "quarantine_reason", "notify_participants" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_output" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.participant_dispatch_for_run" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.federated_output", "hospitality.participant_dispatch_attempt" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.quarantine_federated_output:apply" ] } ], "summary": "Quarantine federated output", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.quarantine_federated_output/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_quarantine_federated_output` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.quarantine_federated_output:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_quarantine_federated_output", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_at": { "format": "date-time", "title": "Defaults to now()", "type": "string" }, "incident_reference": { "title": "External incident ref", "type": "string" }, "notify_participants": { "title": "Whether to notify participants", "type": "boolean" }, "quarantine_reason": { "title": "Required text reason", "type": "string" } }, "required": [ "quarantine_reason", "notify_participants" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_output" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.participant_dispatch_for_run" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.federated_output", "hospitality.participant_dispatch_attempt" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Quarantine federated output (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.quarantine_federated_output/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_quarantine_federated_output`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_quarantine_federated_output", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_at": { "format": "date-time", "title": "Defaults to now()", "type": "string" }, "incident_reference": { "title": "External incident ref", "type": "string" }, "notify_participants": { "title": "Whether to notify participants", "type": "boolean" }, "quarantine_reason": { "title": "Required text reason", "type": "string" } }, "required": [ "quarantine_reason", "notify_participants" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_output" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Quarantine federated output (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.quarantine_federated_output/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_quarantine_federated_output` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.quarantine_federated_output:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_quarantine_federated_output", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_at": { "format": "date-time", "title": "Defaults to now()", "type": "string" }, "incident_reference": { "title": "External incident ref", "type": "string" }, "notify_participants": { "title": "Whether to notify participants", "type": "boolean" }, "quarantine_reason": { "title": "Required text reason", "type": "string" } }, "required": [ "quarantine_reason", "notify_participants" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_output" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Quarantine federated output (rollup delta)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.queue_reservation_for_room/apply": { "post": { "description": "The guest is at the desk and the room is not ready: put the reservation on the room queue (OPERA's queue room). Refuses unless the reservation is pre-check-in with its arrival day reached. The rush signal derives instead of being a second manual write: the assigned room's open housekeeping tasks bump to urgent on the spot. A clean / inspected report on that room later emits room_queue.room_ready (the guest-messaging hook), and check_in fulfils the entry the moment the guest gets the room. Re-queueing a reservation already waiting is a no-op.\n\nEffects: create hospitality.room_queue_entry; link hospitality.link.room_queue_entry_for_reservation; modify hospitality.housekeeping_task.", "operationId": "apply_hospitality_action_queue_reservation_for_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "notes": { "title": "Desk notes (where the guest is waiting, luggage)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.room_queue_entry_for_reservation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.room_queue_entry", "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.queue_reservation_for_room:apply" ] } ], "summary": "Queue reservation for room", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.queue_reservation_for_room/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_queue_reservation_for_room` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.queue_reservation_for_room:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_queue_reservation_for_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "notes": { "title": "Desk notes (where the guest is waiting, luggage)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.room_queue_entry_for_reservation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.room_queue_entry", "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Queue reservation for room (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.queue_reservation_for_room/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_queue_reservation_for_room`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_queue_reservation_for_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "notes": { "title": "Desk notes (where the guest is waiting, luggage)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Queue reservation for room (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.queue_reservation_for_room/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_queue_reservation_for_room` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.queue_reservation_for_room:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_queue_reservation_for_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "notes": { "title": "Desk notes (where the guest is waiting, luggage)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Queue reservation for room (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.quote_group_block/apply": { "post": { "description": "Record a displacement analysis for the target group_request and stamp the operator's decision. The analysis freezes the forecast at decision time; re-decisions create new analysis rows, never mutations.\n\nEffects: create hospitality.group_displacement_analysis; modify hospitality.group_request; link hospitality.link.displacement_analysis_for_request.", "operationId": "apply_hospitality_action_quote_group_block", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "counter_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Counter offer rate (required when decision = counter)", "type": "object" }, "decision": { "enum": [ "accept", "decline", "counter" ], "title": "Decision", "type": "string" }, "decision_notes": { "title": "Decision notes", "type": "string" }, "displaced_contribution": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Forfeited transient contribution", "type": "object" }, "displaced_room_nights": { "title": "Displaced transient room nights", "type": "integer" }, "forecast_snapshot": { "additionalProperties": true, "title": "Forecast at decision time", "type": "object" }, "group_total_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Group total revenue", "type": "object" }, "group_variable_cost": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Group variable cost", "type": "object" }, "minimum_acceptable_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Minimum acceptable ADR", "type": "object" }, "variable_cost_per_room": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Variable cost per room", "type": "object" } }, "required": [ "forecast_snapshot", "variable_cost_per_room", "displaced_room_nights", "displaced_contribution", "group_total_revenue", "group_variable_cost", "minimum_acceptable_rate", "decision" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_request" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.displacement_analysis_for_request" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.group_displacement_analysis", "hospitality.group_request" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.quote_group_block:apply" ] } ], "summary": "Quote group block", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.quote_group_block/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_quote_group_block` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.quote_group_block:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_quote_group_block", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "counter_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Counter offer rate (required when decision = counter)", "type": "object" }, "decision": { "enum": [ "accept", "decline", "counter" ], "title": "Decision", "type": "string" }, "decision_notes": { "title": "Decision notes", "type": "string" }, "displaced_contribution": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Forfeited transient contribution", "type": "object" }, "displaced_room_nights": { "title": "Displaced transient room nights", "type": "integer" }, "forecast_snapshot": { "additionalProperties": true, "title": "Forecast at decision time", "type": "object" }, "group_total_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Group total revenue", "type": "object" }, "group_variable_cost": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Group variable cost", "type": "object" }, "minimum_acceptable_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Minimum acceptable ADR", "type": "object" }, "variable_cost_per_room": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Variable cost per room", "type": "object" } }, "required": [ "forecast_snapshot", "variable_cost_per_room", "displaced_room_nights", "displaced_contribution", "group_total_revenue", "group_variable_cost", "minimum_acceptable_rate", "decision" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_request" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.displacement_analysis_for_request" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.group_displacement_analysis", "hospitality.group_request" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Quote group block (dry-run)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.quote_group_block/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_quote_group_block`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_quote_group_block", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "counter_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Counter offer rate (required when decision = counter)", "type": "object" }, "decision": { "enum": [ "accept", "decline", "counter" ], "title": "Decision", "type": "string" }, "decision_notes": { "title": "Decision notes", "type": "string" }, "displaced_contribution": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Forfeited transient contribution", "type": "object" }, "displaced_room_nights": { "title": "Displaced transient room nights", "type": "integer" }, "forecast_snapshot": { "additionalProperties": true, "title": "Forecast at decision time", "type": "object" }, "group_total_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Group total revenue", "type": "object" }, "group_variable_cost": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Group variable cost", "type": "object" }, "minimum_acceptable_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Minimum acceptable ADR", "type": "object" }, "variable_cost_per_room": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Variable cost per room", "type": "object" } }, "required": [ "forecast_snapshot", "variable_cost_per_room", "displaced_room_nights", "displaced_contribution", "group_total_revenue", "group_variable_cost", "minimum_acceptable_rate", "decision" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_request" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Quote group block (dry-run)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.quote_group_block/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_quote_group_block` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.quote_group_block:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_quote_group_block", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "counter_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Counter offer rate (required when decision = counter)", "type": "object" }, "decision": { "enum": [ "accept", "decline", "counter" ], "title": "Decision", "type": "string" }, "decision_notes": { "title": "Decision notes", "type": "string" }, "displaced_contribution": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Forfeited transient contribution", "type": "object" }, "displaced_room_nights": { "title": "Displaced transient room nights", "type": "integer" }, "forecast_snapshot": { "additionalProperties": true, "title": "Forecast at decision time", "type": "object" }, "group_total_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Group total revenue", "type": "object" }, "group_variable_cost": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Group variable cost", "type": "object" }, "minimum_acceptable_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Minimum acceptable ADR", "type": "object" }, "variable_cost_per_room": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Variable cost per room", "type": "object" } }, "required": [ "forecast_snapshot", "variable_cost_per_room", "displaced_room_nights", "displaced_contribution", "group_total_revenue", "group_variable_cost", "minimum_acceptable_rate", "decision" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_request" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Quote group block (rollup delta)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.raise_maintenance_work_order/apply": { "post": { "description": "Raise a scheduled plan's work order — the automation sweep's effect when `next_due_on` comes, or the desk pulling it forward. Creates the order through `create_work_order`'s own path against the plan's room (and for the plan's asset, when it names one), scheduled for the due date and stamped with the plan's id (`maintenance_plan_id`), links it to the plan, and marks the plan `raised` until the order closes. A no-op on a plan already raised (one open order per plan, so a repeated firing raises nothing); refuses a retired plan. Emits `maintenance_plan.raised`.\n\nEffects: modify hospitality.maintenance_plan; link hospitality.link.work_order_from_maintenance_plan; modify hospitality.work_order; create hospitality.work_order; link hospitality.link.work_order_from_triage; link hospitality.link.work_order_for_room; link hospitality.link.work_order_assigned_to; create hospitality.room_status_block; link hospitality.link.room_status_block_for_room; link hospitality.link.work_order_holds_block; modify hospitality.availability_day; link hospitality.link.work_order_for_asset; link hospitality.link.work_order_reported_by_stay; link hospitality.link.work_order_of_fault_type; link hospitality.link.work_order_for_area.", "operationId": "apply_hospitality_action_raise_maintenance_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.maintenance_plan" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.work_order_from_maintenance_plan", "hospitality.link.work_order_from_triage", "hospitality.link.work_order_for_room", "hospitality.link.work_order_assigned_to", "hospitality.link.room_status_block_for_room", "hospitality.link.work_order_holds_block", "hospitality.link.work_order_for_asset", "hospitality.link.work_order_reported_by_stay", "hospitality.link.work_order_of_fault_type", "hospitality.link.work_order_for_area" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.maintenance_plan", "hospitality.work_order", "hospitality.room_status_block", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.raise_maintenance_work_order:apply" ] } ], "summary": "Raise maintenance work order", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.raise_maintenance_work_order/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_raise_maintenance_work_order` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.raise_maintenance_work_order:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_raise_maintenance_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.maintenance_plan" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.work_order_from_maintenance_plan", "hospitality.link.work_order_from_triage", "hospitality.link.work_order_for_room", "hospitality.link.work_order_assigned_to", "hospitality.link.room_status_block_for_room", "hospitality.link.work_order_holds_block", "hospitality.link.work_order_for_asset", "hospitality.link.work_order_reported_by_stay", "hospitality.link.work_order_of_fault_type", "hospitality.link.work_order_for_area" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.maintenance_plan", "hospitality.work_order", "hospitality.room_status_block", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Raise maintenance work order (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.raise_maintenance_work_order/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_raise_maintenance_work_order`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_raise_maintenance_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.maintenance_plan" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Raise maintenance work order (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.raise_maintenance_work_order/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_raise_maintenance_work_order` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.raise_maintenance_work_order:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_raise_maintenance_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.maintenance_plan" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Raise maintenance work order (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.raise_work_order_from_feedback/apply": { "post": { "description": "Raise a work order for the fault a complaint or a suggestion reports — hubOS's fault linked to a complaint. The order is created through `create_work_order`'s own path against `room_id`, or the feedback's stay's room when none is named, and links back (`work_order_answers_feedback`); an open case moves to `in_progress`. The feedback's text is never copied onto the order — it is the guest's, the order is read by engineering — so the title and description are the house's words. Refuses a compliment and a closed case. A complaint may need more than one order; each call raises one. Emits `guest_feedback.work_order_raised`.\n\nEffects: modify hospitality.guest_feedback; link hospitality.link.work_order_answers_feedback; create hospitality.work_order; link hospitality.link.work_order_from_triage; link hospitality.link.work_order_for_room; link hospitality.link.work_order_assigned_to; create hospitality.room_status_block; link hospitality.link.room_status_block_for_room; link hospitality.link.work_order_holds_block; modify hospitality.availability_day; link hospitality.link.work_order_for_asset; link hospitality.link.work_order_reported_by_stay; link hospitality.link.work_order_of_fault_type; link hospitality.link.work_order_for_area.", "operationId": "apply_hospitality_action_raise_work_order_from_feedback", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "Work order category", "type": "string" }, "description": { "title": "What engineering needs to know", "type": "string" }, "room_id": { "format": "uuid", "title": "The room (defaults to the feedback's stay's room)", "type": "string", "x-aerandil-references": "hospitality.room" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "title": "Work order severity", "type": "string" }, "staff_member_id": { "format": "uuid", "title": "Engineer to assign on creation", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "title": { "title": "Title", "type": "string" } }, "required": [ "title", "category", "severity" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.work_order_answers_feedback", "hospitality.link.work_order_from_triage", "hospitality.link.work_order_for_room", "hospitality.link.work_order_assigned_to", "hospitality.link.room_status_block_for_room", "hospitality.link.work_order_holds_block", "hospitality.link.work_order_for_asset", "hospitality.link.work_order_reported_by_stay", "hospitality.link.work_order_of_fault_type", "hospitality.link.work_order_for_area" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.guest_feedback", "hospitality.work_order", "hospitality.room_status_block", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.raise_work_order_from_feedback:apply" ] } ], "summary": "Raise work order from feedback", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.raise_work_order_from_feedback/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_raise_work_order_from_feedback` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.raise_work_order_from_feedback:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_raise_work_order_from_feedback", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "Work order category", "type": "string" }, "description": { "title": "What engineering needs to know", "type": "string" }, "room_id": { "format": "uuid", "title": "The room (defaults to the feedback's stay's room)", "type": "string", "x-aerandil-references": "hospitality.room" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "title": "Work order severity", "type": "string" }, "staff_member_id": { "format": "uuid", "title": "Engineer to assign on creation", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "title": { "title": "Title", "type": "string" } }, "required": [ "title", "category", "severity" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.work_order_answers_feedback", "hospitality.link.work_order_from_triage", "hospitality.link.work_order_for_room", "hospitality.link.work_order_assigned_to", "hospitality.link.room_status_block_for_room", "hospitality.link.work_order_holds_block", "hospitality.link.work_order_for_asset", "hospitality.link.work_order_reported_by_stay", "hospitality.link.work_order_of_fault_type", "hospitality.link.work_order_for_area" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.guest_feedback", "hospitality.work_order", "hospitality.room_status_block", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Raise work order from feedback (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.raise_work_order_from_feedback/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_raise_work_order_from_feedback`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_raise_work_order_from_feedback", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "Work order category", "type": "string" }, "description": { "title": "What engineering needs to know", "type": "string" }, "room_id": { "format": "uuid", "title": "The room (defaults to the feedback's stay's room)", "type": "string", "x-aerandil-references": "hospitality.room" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "title": "Work order severity", "type": "string" }, "staff_member_id": { "format": "uuid", "title": "Engineer to assign on creation", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "title": { "title": "Title", "type": "string" } }, "required": [ "title", "category", "severity" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Raise work order from feedback (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.raise_work_order_from_feedback/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_raise_work_order_from_feedback` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.raise_work_order_from_feedback:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_raise_work_order_from_feedback", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "Work order category", "type": "string" }, "description": { "title": "What engineering needs to know", "type": "string" }, "room_id": { "format": "uuid", "title": "The room (defaults to the feedback's stay's room)", "type": "string", "x-aerandil-references": "hospitality.room" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "title": "Work order severity", "type": "string" }, "staff_member_id": { "format": "uuid", "title": "Engineer to assign on creation", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "title": { "title": "Title", "type": "string" } }, "required": [ "title", "category", "severity" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Raise work order from feedback (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.recall_ticket/apply": { "post": { "description": "Re-open a bumped ticket (Toast recall/unfulfill — bumped by mistake, or the pass rejected the plate). The ticket returns to the board as `recalled` and its fulfilled lines drop back to `fired`; bumping again re-fulfils. Emits `fnb.ticket_recalled`.\n\nEffects: modify hospitality.kitchen_ticket; modify hospitality.check_line.", "operationId": "apply_hospitality_action_recall_ticket", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.kitchen_ticket" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.kitchen_ticket", "hospitality.check_line" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.recall_ticket:apply" ] } ], "summary": "Recall ticket", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.recall_ticket/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_recall_ticket` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.recall_ticket:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_recall_ticket", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.kitchen_ticket" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.kitchen_ticket", "hospitality.check_line" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Recall ticket (dry-run)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.recall_ticket/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_recall_ticket`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_recall_ticket", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.kitchen_ticket" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Recall ticket (dry-run)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.recall_ticket/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_recall_ticket` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.recall_ticket:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_recall_ticket", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.kitchen_ticket" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Recall ticket (rollup delta)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.receive_channel_reservation/apply": { "post": { "description": "Record an inbound reservation message from a partner, keyed on their message id. A replay returns the existing delivery untouched rather than minting a second one: every channel wire is at-least-once, so duplicate delivery is the norm and de-duplication here is what stops one OTA booking becoming three. Recording is deliberately separate from applying — a message we cannot yet act on is still a message we received, and losing it because the booking failed is how an OTA reservation goes missing. `origin_channel_code` is kept verbatim even when it maps to no `channel` row, because an unrecognised code is exactly the signal to add one. Emits `channel_reservation.received`.\n\nEffects: create hospitality.channel_reservation_delivery; link hospitality.link.reservation_delivery_for_connection; link hospitality.link.reservation_delivery_from_channel.", "operationId": "apply_hospitality_action_receive_channel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "external_message_id": { "title": "The partner's identifier for this message (de-duplication key)", "type": "string" }, "external_reservation_id": { "title": "The partner's identifier for the reservation (stable across book/modify/cancel)", "type": "string" }, "intent": { "enum": [ "book", "modify", "cancel" ], "title": "What the message asks of us", "type": "string" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "origin_channel_code": { "title": "The partner's code for the demand channel that sold the booking", "type": "string" }, "payload_digest": { "title": "Digest of the verbatim partner payload held in raw staging", "type": "string" } }, "required": [ "external_message_id", "external_reservation_id", "intent" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.reservation_delivery_for_connection", "hospitality.link.reservation_delivery_from_channel" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.channel_reservation_delivery" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.receive_channel_reservation:apply" ] } ], "summary": "Receive channel reservation", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.receive_channel_reservation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_receive_channel_reservation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.receive_channel_reservation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_receive_channel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "external_message_id": { "title": "The partner's identifier for this message (de-duplication key)", "type": "string" }, "external_reservation_id": { "title": "The partner's identifier for the reservation (stable across book/modify/cancel)", "type": "string" }, "intent": { "enum": [ "book", "modify", "cancel" ], "title": "What the message asks of us", "type": "string" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "origin_channel_code": { "title": "The partner's code for the demand channel that sold the booking", "type": "string" }, "payload_digest": { "title": "Digest of the verbatim partner payload held in raw staging", "type": "string" } }, "required": [ "external_message_id", "external_reservation_id", "intent" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.reservation_delivery_for_connection", "hospitality.link.reservation_delivery_from_channel" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.channel_reservation_delivery" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Receive channel reservation (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.receive_channel_reservation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_receive_channel_reservation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_receive_channel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "external_message_id": { "title": "The partner's identifier for this message (de-duplication key)", "type": "string" }, "external_reservation_id": { "title": "The partner's identifier for the reservation (stable across book/modify/cancel)", "type": "string" }, "intent": { "enum": [ "book", "modify", "cancel" ], "title": "What the message asks of us", "type": "string" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "origin_channel_code": { "title": "The partner's code for the demand channel that sold the booking", "type": "string" }, "payload_digest": { "title": "Digest of the verbatim partner payload held in raw staging", "type": "string" } }, "required": [ "external_message_id", "external_reservation_id", "intent" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Receive channel reservation (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.receive_channel_reservation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_receive_channel_reservation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.receive_channel_reservation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_receive_channel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "external_message_id": { "title": "The partner's identifier for this message (de-duplication key)", "type": "string" }, "external_reservation_id": { "title": "The partner's identifier for the reservation (stable across book/modify/cancel)", "type": "string" }, "intent": { "enum": [ "book", "modify", "cancel" ], "title": "What the message asks of us", "type": "string" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "origin_channel_code": { "title": "The partner's code for the demand channel that sold the booking", "type": "string" }, "payload_digest": { "title": "Digest of the verbatim partner payload held in raw staging", "type": "string" } }, "required": [ "external_message_id", "external_reservation_id", "intent" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Receive channel reservation (rollup delta)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.receive_stock/apply": { "post": { "description": "Record stock arriving at a store — a delivery — as a `receipt` movement, and move the store's level for the material up by it in the same transaction (minting the level on the pair's first movement). A retired material refuses. Replay-safe under the apply route's Idempotency-Key.\n\nEffects: create hospitality.stock_movement; create hospitality.stock_level; modify hospitality.stock_level; link hospitality.link.stock_movement_for_level; link hospitality.link.stock_level_for_material; link hospitality.link.stock_level_in_store; link hospitality.link.stock_movement_recorded_by.", "operationId": "apply_hospitality_action_receive_stock", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "material_id": { "format": "uuid", "title": "The material", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "title": "How much arrived, in the material's unit (more than zero)", "type": "string" }, "reason": { "title": "Notes", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When it happened (defaults to now; a handset queueing offline sends its own time; refused when more than five minutes ahead of the kernel's clock)", "type": "string" }, "reference": { "title": "The supplier's delivery note or invoice number", "type": "string" } }, "required": [ "material_id", "quantity" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_store" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.stock_movement_for_level", "hospitality.link.stock_level_for_material", "hospitality.link.stock_level_in_store", "hospitality.link.stock_movement_recorded_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.stock_movement", "hospitality.stock_level" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.receive_stock:apply" ] } ], "summary": "Receive stock", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.receive_stock/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_receive_stock` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.receive_stock:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_receive_stock", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "material_id": { "format": "uuid", "title": "The material", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "title": "How much arrived, in the material's unit (more than zero)", "type": "string" }, "reason": { "title": "Notes", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When it happened (defaults to now; a handset queueing offline sends its own time; refused when more than five minutes ahead of the kernel's clock)", "type": "string" }, "reference": { "title": "The supplier's delivery note or invoice number", "type": "string" } }, "required": [ "material_id", "quantity" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_store" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.stock_movement_for_level", "hospitality.link.stock_level_for_material", "hospitality.link.stock_level_in_store", "hospitality.link.stock_movement_recorded_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.stock_movement", "hospitality.stock_level" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Receive stock (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.receive_stock/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_receive_stock`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_receive_stock", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "material_id": { "format": "uuid", "title": "The material", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "title": "How much arrived, in the material's unit (more than zero)", "type": "string" }, "reason": { "title": "Notes", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When it happened (defaults to now; a handset queueing offline sends its own time; refused when more than five minutes ahead of the kernel's clock)", "type": "string" }, "reference": { "title": "The supplier's delivery note or invoice number", "type": "string" } }, "required": [ "material_id", "quantity" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_store" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Receive stock (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.receive_stock/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_receive_stock` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.receive_stock:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_receive_stock", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "material_id": { "format": "uuid", "title": "The material", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "title": "How much arrived, in the material's unit (more than zero)", "type": "string" }, "reason": { "title": "Notes", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When it happened (defaults to now; a handset queueing offline sends its own time; refused when more than five minutes ahead of the kernel's clock)", "type": "string" }, "reference": { "title": "The supplier's delivery note or invoice number", "type": "string" } }, "required": [ "material_id", "quantity" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_store" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Receive stock (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.reclaim_housekeeping_task/apply": { "post": { "description": "Take an assigned task that has not been started from whoever holds it (hubOS's reclaim): the assignment edge re-points to the acting staff member in one write. Refused once the task is started (in progress, or blocked after a start), finished or skipped; refused on a task nobody holds (start it to take it) and on one held by a worker group (a member takes it by starting it). A supervisor (housekeeping or front-office supervisor, manager on duty, general manager, owner) — or a caller that is not a staff member — may name `assignee_id` to reclaim it onto someone at the task's house; anyone else reclaims only for themself. Reclaiming onto the current holder is a no-op, checked before the state — a Take sent again after the taker started the room lands once. `expected_holder_id` names the holder the caller saw (a Take queued on a handset): refused when someone else holds the task by the time it lands, so a queued Take replays safely. Two Takes or assigns of one task queue on its holder lock. Emits `housekeeping.task.reclaimed` with the previous assignee; the new assignee's handset is nudged as for an assignment.\n\nEffects: link hospitality.link.housekeeping_task_assigned_to; unlink hospitality.link.housekeeping_task_assigned_to; modify hospitality.housekeeping_task.", "operationId": "apply_hospitality_action_reclaim_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "assignee_id": { "format": "uuid", "title": "Who takes it (a supervisor's choice; defaults to the caller)", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "expected_holder_id": { "format": "uuid", "title": "Who the caller saw holding it — refused when that has changed", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.housekeeping_task_assigned_to" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.reclaim_housekeeping_task:apply" ] } ], "summary": "Reclaim housekeeping task", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.reclaim_housekeeping_task/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_reclaim_housekeeping_task` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.reclaim_housekeeping_task:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_reclaim_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "assignee_id": { "format": "uuid", "title": "Who takes it (a supervisor's choice; defaults to the caller)", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "expected_holder_id": { "format": "uuid", "title": "Who the caller saw holding it — refused when that has changed", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.housekeeping_task_assigned_to" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Reclaim housekeeping task (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.reclaim_housekeeping_task/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_reclaim_housekeeping_task`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_reclaim_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "assignee_id": { "format": "uuid", "title": "Who takes it (a supervisor's choice; defaults to the caller)", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "expected_holder_id": { "format": "uuid", "title": "Who the caller saw holding it — refused when that has changed", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Reclaim housekeeping task (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.reclaim_housekeeping_task/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_reclaim_housekeeping_task` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.reclaim_housekeeping_task:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_reclaim_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "assignee_id": { "format": "uuid", "title": "Who takes it (a supervisor's choice; defaults to the caller)", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "expected_holder_id": { "format": "uuid", "title": "Who the caller saw holding it — refused when that has changed", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Reclaim housekeeping task (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.reclaim_work_order/apply": { "post": { "description": "Take an assigned work order that has not been started from whoever holds it (hubOS's reclaim): the assignment edge re-points to the acting staff member in one write. Refused once the order is under way (in progress, or blocked or postponed after a start), complete or void; refused on an order nobody holds and on one held by a worker group; refused to a runner or a housekeeper — a fault is worked by engineering. A supervisor (housekeeping or front-office supervisor, manager on duty, general manager, owner) — or a caller that is not a staff member — may name `assignee_id` to reclaim it onto someone at the order's house; anyone else reclaims only for themself. Reclaiming onto the current holder is a no-op, checked before the state — a Take sent again after the start lands once. `expected_holder_id` names the holder the caller saw (a Take queued on a handset): refused when someone else holds the order by the time it lands, so a queued Take replays safely. Two Takes or assigns of one order queue on its holder lock. Emits `work_order.reclaimed` with the previous assignee; the new assignee's handset is nudged as for an assignment.\n\nEffects: link hospitality.link.work_order_assigned_to; unlink hospitality.link.work_order_assigned_to; modify hospitality.work_order.", "operationId": "apply_hospitality_action_reclaim_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "assignee_id": { "format": "uuid", "title": "Who takes it (a supervisor's choice; defaults to the caller)", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "expected_holder_id": { "format": "uuid", "title": "Who the caller saw holding it — refused when that has changed", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.work_order_assigned_to" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.work_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.reclaim_work_order:apply" ] } ], "summary": "Reclaim work order", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.reclaim_work_order/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_reclaim_work_order` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.reclaim_work_order:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_reclaim_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "assignee_id": { "format": "uuid", "title": "Who takes it (a supervisor's choice; defaults to the caller)", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "expected_holder_id": { "format": "uuid", "title": "Who the caller saw holding it — refused when that has changed", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.work_order_assigned_to" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.work_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Reclaim work order (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.reclaim_work_order/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_reclaim_work_order`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_reclaim_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "assignee_id": { "format": "uuid", "title": "Who takes it (a supervisor's choice; defaults to the caller)", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "expected_holder_id": { "format": "uuid", "title": "Who the caller saw holding it — refused when that has changed", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Reclaim work order (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.reclaim_work_order/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_reclaim_work_order` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.reclaim_work_order:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_reclaim_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "assignee_id": { "format": "uuid", "title": "Who takes it (a supervisor's choice; defaults to the caller)", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "expected_holder_id": { "format": "uuid", "title": "Who the caller saw holding it — refused when that has changed", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Reclaim work order (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.recognise_person/apply": { "post": { "description": "Move a person up the four-rung local_status ladder (not_local → observed_local → known_regular → named_recognised). The status overwrites the existing `relationship_context.local_status`; the companion `local_status_computed_at` records the transition time. When `venue_id` is provided, a temporal `person_frequents_venue` link is created for the cross-property recognition handoff.\n\nEffects: modify hospitality.person; link hospitality.link.person_frequents_venue.", "operationId": "apply_hospitality_action_recognise_person", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "new_local_status": { "enum": [ "not_local", "observed_local", "known_regular", "named_recognised" ], "title": "New local status", "type": "string" }, "person_id": { "format": "uuid", "title": "Person being recognised", "type": "string", "x-aerandil-references": "hospitality.person" }, "recognised_at": { "format": "date-time", "title": "Recognition timestamp", "type": "string" }, "recogniser": { "title": "Recogniser principal identifier", "type": "string" }, "venue_id": { "format": "uuid", "title": "Venue (when recognition is venue-scoped)", "type": "string", "x-aerandil-references": "hospitality.venue" } }, "required": [ "person_id", "new_local_status", "recogniser", "recognised_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.person_frequents_venue" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.person" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.recognise_person:apply" ] } ], "summary": "Recognise person", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.recognise_person/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_recognise_person` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.recognise_person:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_recognise_person", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "new_local_status": { "enum": [ "not_local", "observed_local", "known_regular", "named_recognised" ], "title": "New local status", "type": "string" }, "person_id": { "format": "uuid", "title": "Person being recognised", "type": "string", "x-aerandil-references": "hospitality.person" }, "recognised_at": { "format": "date-time", "title": "Recognition timestamp", "type": "string" }, "recogniser": { "title": "Recogniser principal identifier", "type": "string" }, "venue_id": { "format": "uuid", "title": "Venue (when recognition is venue-scoped)", "type": "string", "x-aerandil-references": "hospitality.venue" } }, "required": [ "person_id", "new_local_status", "recogniser", "recognised_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.person_frequents_venue" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.person" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Recognise person (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.recognise_person/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_recognise_person`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_recognise_person", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "new_local_status": { "enum": [ "not_local", "observed_local", "known_regular", "named_recognised" ], "title": "New local status", "type": "string" }, "person_id": { "format": "uuid", "title": "Person being recognised", "type": "string", "x-aerandil-references": "hospitality.person" }, "recognised_at": { "format": "date-time", "title": "Recognition timestamp", "type": "string" }, "recogniser": { "title": "Recogniser principal identifier", "type": "string" }, "venue_id": { "format": "uuid", "title": "Venue (when recognition is venue-scoped)", "type": "string", "x-aerandil-references": "hospitality.venue" } }, "required": [ "person_id", "new_local_status", "recogniser", "recognised_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Recognise person (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.recognise_person/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_recognise_person` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.recognise_person:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_recognise_person", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "new_local_status": { "enum": [ "not_local", "observed_local", "known_regular", "named_recognised" ], "title": "New local status", "type": "string" }, "person_id": { "format": "uuid", "title": "Person being recognised", "type": "string", "x-aerandil-references": "hospitality.person" }, "recognised_at": { "format": "date-time", "title": "Recognition timestamp", "type": "string" }, "recogniser": { "title": "Recogniser principal identifier", "type": "string" }, "venue_id": { "format": "uuid", "title": "Venue (when recognition is venue-scoped)", "type": "string", "x-aerandil-references": "hospitality.venue" } }, "required": [ "person_id", "new_local_status", "recogniser", "recognised_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Recognise person (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.recommend_rate/apply": { "post": { "description": "Emit a typed rate recommendation. The agent payload (recommended_amount, current_amount, confidence, factors, forecast_snapshot, rationale) lands as a `rate_recommendation` row in `suggested` state with an immutable forecast snapshot captured at issue time. Decision lifecycle then flows through `apply_rate_recommendation` / `reject_rate_recommendation` / `expire_rate_recommendations`.\n\nEffects: create hospitality.rate_recommendation; create hospitality.rate_recommendation_run; modify hospitality.rate_recommendation_run; link hospitality.link.recommendation_for_rate_plan; link hospitality.link.recommendation_for_room_type; link hospitality.link.recommendation_at_property; link hospitality.link.recommendation_part_of_run; link hospitality.link.run_for_property; link hospitality.link.recommendation_superseded_by; modify hospitality.rate_recommendation.", "operationId": "apply_hospitality_action_recommend_rate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" }, "cadence": { "enum": [ "nightly", "intraday", "hourly", "event_triggered", "manual" ], "title": "Run cadence (used only when opening a fresh run)", "type": "string" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Calibrated probability (optional)", "type": "string" }, "current_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Snapshot of the target amount at issue time", "type": "object" }, "expires_at": { "format": "date-time", "title": "Recommendation expiry (default: issued_at + 4h when absent)", "type": "string" }, "expires_on": { "format": "date", "title": "The house business day the recommendation lapses after, in place of `expires_at`: the house's open business date decides expiry, not the wall clock, so a day's recommendations apply on that business day however late it closes", "type": "string" }, "factors_considered": { "items": { "enum": [ "pickup_pace", "booking_curve", "competitive_set", "event_calendar", "historical_pattern", "segment_mix", "channel_mix", "length_of_stay_distribution", "cancellation_rate", "no_show_rate", "package_attachment", "group_displacement", "weather", "other" ], "type": "string" }, "title": "Signals that drove the recommendation", "type": "array" }, "forecast_snapshot": { "additionalProperties": true, "title": "Forecast snapshot (struct as JSON)", "type": "object" }, "occupancy": { "title": "Occupancy (adult count)", "type": "integer" }, "property_id": { "title": "Property the recommendation applies to", "type": "string" }, "rationale_text": { "title": "Human-readable explanation", "type": "string" }, "recommended_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Proposed new amount", "type": "object" }, "room_type_id": { "title": "Room type the recommendation applies to", "type": "string" }, "run_id": { "title": "Existing run to append to (handler opens one when absent)", "type": "string" }, "target_field": { "enum": [ "bar_anchor", "amount" ], "title": "Target rate_per_night field", "type": "string" }, "target_horizon_days": { "title": "Forecast horizon the run looked over", "type": "integer" } }, "required": [ "room_type_id", "property_id", "business_date", "occupancy", "target_field", "current_amount", "recommended_amount", "confidence", "factors_considered", "rationale_text", "forecast_snapshot" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_plan" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.recommendation_for_rate_plan", "hospitality.link.recommendation_for_room_type", "hospitality.link.recommendation_at_property", "hospitality.link.recommendation_part_of_run", "hospitality.link.run_for_property", "hospitality.link.recommendation_superseded_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.rate_recommendation", "hospitality.rate_recommendation_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.recommend_rate:apply" ] } ], "summary": "Recommend rate", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.recommend_rate/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_recommend_rate` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.recommend_rate:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_recommend_rate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" }, "cadence": { "enum": [ "nightly", "intraday", "hourly", "event_triggered", "manual" ], "title": "Run cadence (used only when opening a fresh run)", "type": "string" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Calibrated probability (optional)", "type": "string" }, "current_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Snapshot of the target amount at issue time", "type": "object" }, "expires_at": { "format": "date-time", "title": "Recommendation expiry (default: issued_at + 4h when absent)", "type": "string" }, "expires_on": { "format": "date", "title": "The house business day the recommendation lapses after, in place of `expires_at`: the house's open business date decides expiry, not the wall clock, so a day's recommendations apply on that business day however late it closes", "type": "string" }, "factors_considered": { "items": { "enum": [ "pickup_pace", "booking_curve", "competitive_set", "event_calendar", "historical_pattern", "segment_mix", "channel_mix", "length_of_stay_distribution", "cancellation_rate", "no_show_rate", "package_attachment", "group_displacement", "weather", "other" ], "type": "string" }, "title": "Signals that drove the recommendation", "type": "array" }, "forecast_snapshot": { "additionalProperties": true, "title": "Forecast snapshot (struct as JSON)", "type": "object" }, "occupancy": { "title": "Occupancy (adult count)", "type": "integer" }, "property_id": { "title": "Property the recommendation applies to", "type": "string" }, "rationale_text": { "title": "Human-readable explanation", "type": "string" }, "recommended_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Proposed new amount", "type": "object" }, "room_type_id": { "title": "Room type the recommendation applies to", "type": "string" }, "run_id": { "title": "Existing run to append to (handler opens one when absent)", "type": "string" }, "target_field": { "enum": [ "bar_anchor", "amount" ], "title": "Target rate_per_night field", "type": "string" }, "target_horizon_days": { "title": "Forecast horizon the run looked over", "type": "integer" } }, "required": [ "room_type_id", "property_id", "business_date", "occupancy", "target_field", "current_amount", "recommended_amount", "confidence", "factors_considered", "rationale_text", "forecast_snapshot" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_plan" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.recommendation_for_rate_plan", "hospitality.link.recommendation_for_room_type", "hospitality.link.recommendation_at_property", "hospitality.link.recommendation_part_of_run", "hospitality.link.run_for_property", "hospitality.link.recommendation_superseded_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.rate_recommendation", "hospitality.rate_recommendation_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Recommend rate (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.recommend_rate/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_recommend_rate`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_recommend_rate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" }, "cadence": { "enum": [ "nightly", "intraday", "hourly", "event_triggered", "manual" ], "title": "Run cadence (used only when opening a fresh run)", "type": "string" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Calibrated probability (optional)", "type": "string" }, "current_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Snapshot of the target amount at issue time", "type": "object" }, "expires_at": { "format": "date-time", "title": "Recommendation expiry (default: issued_at + 4h when absent)", "type": "string" }, "expires_on": { "format": "date", "title": "The house business day the recommendation lapses after, in place of `expires_at`: the house's open business date decides expiry, not the wall clock, so a day's recommendations apply on that business day however late it closes", "type": "string" }, "factors_considered": { "items": { "enum": [ "pickup_pace", "booking_curve", "competitive_set", "event_calendar", "historical_pattern", "segment_mix", "channel_mix", "length_of_stay_distribution", "cancellation_rate", "no_show_rate", "package_attachment", "group_displacement", "weather", "other" ], "type": "string" }, "title": "Signals that drove the recommendation", "type": "array" }, "forecast_snapshot": { "additionalProperties": true, "title": "Forecast snapshot (struct as JSON)", "type": "object" }, "occupancy": { "title": "Occupancy (adult count)", "type": "integer" }, "property_id": { "title": "Property the recommendation applies to", "type": "string" }, "rationale_text": { "title": "Human-readable explanation", "type": "string" }, "recommended_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Proposed new amount", "type": "object" }, "room_type_id": { "title": "Room type the recommendation applies to", "type": "string" }, "run_id": { "title": "Existing run to append to (handler opens one when absent)", "type": "string" }, "target_field": { "enum": [ "bar_anchor", "amount" ], "title": "Target rate_per_night field", "type": "string" }, "target_horizon_days": { "title": "Forecast horizon the run looked over", "type": "integer" } }, "required": [ "room_type_id", "property_id", "business_date", "occupancy", "target_field", "current_amount", "recommended_amount", "confidence", "factors_considered", "rationale_text", "forecast_snapshot" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_plan" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Recommend rate (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.recommend_rate/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_recommend_rate` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.recommend_rate:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_recommend_rate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" }, "cadence": { "enum": [ "nightly", "intraday", "hourly", "event_triggered", "manual" ], "title": "Run cadence (used only when opening a fresh run)", "type": "string" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Calibrated probability (optional)", "type": "string" }, "current_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Snapshot of the target amount at issue time", "type": "object" }, "expires_at": { "format": "date-time", "title": "Recommendation expiry (default: issued_at + 4h when absent)", "type": "string" }, "expires_on": { "format": "date", "title": "The house business day the recommendation lapses after, in place of `expires_at`: the house's open business date decides expiry, not the wall clock, so a day's recommendations apply on that business day however late it closes", "type": "string" }, "factors_considered": { "items": { "enum": [ "pickup_pace", "booking_curve", "competitive_set", "event_calendar", "historical_pattern", "segment_mix", "channel_mix", "length_of_stay_distribution", "cancellation_rate", "no_show_rate", "package_attachment", "group_displacement", "weather", "other" ], "type": "string" }, "title": "Signals that drove the recommendation", "type": "array" }, "forecast_snapshot": { "additionalProperties": true, "title": "Forecast snapshot (struct as JSON)", "type": "object" }, "occupancy": { "title": "Occupancy (adult count)", "type": "integer" }, "property_id": { "title": "Property the recommendation applies to", "type": "string" }, "rationale_text": { "title": "Human-readable explanation", "type": "string" }, "recommended_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Proposed new amount", "type": "object" }, "room_type_id": { "title": "Room type the recommendation applies to", "type": "string" }, "run_id": { "title": "Existing run to append to (handler opens one when absent)", "type": "string" }, "target_field": { "enum": [ "bar_anchor", "amount" ], "title": "Target rate_per_night field", "type": "string" }, "target_horizon_days": { "title": "Forecast horizon the run looked over", "type": "integer" } }, "required": [ "room_type_id", "property_id", "business_date", "occupancy", "target_field", "current_amount", "recommended_amount", "confidence", "factors_considered", "rationale_text", "forecast_snapshot" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_plan" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Recommend rate (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.recommend_restriction/apply": { "post": { "description": "Emit a typed sell-restriction recommendation against the target property: a closure (`closed`), closed-to-arrival / departure, or a length-of-stay bound over `start_date..=end_date`, scoped to a room type, a rate plan, or the pair (at least one). At least one constraint must be set. The reading behind it — rooms remaining, the protection level, the demand and sell-up believed — and the forecast snapshot are frozen at issue as a `restriction_recommendation` in `suggested` state; a still- suggested prior against the same scope and range is superseded. Decision lifecycle flows through `apply_restriction_recommendation` / `reject_restriction_recommendation` / `expire_restriction_recommendations`. Joins an in-progress `rate_recommendation_run` when `run_id` is given and opens one otherwise; a run carries rate and restriction recommendations side by side. With `lift` it recommends the re-open instead: no constraint, and its apply lifts the rows standing in exactly this scope over the range.\n\nEffects: create hospitality.restriction_recommendation; modify hospitality.restriction_recommendation; create hospitality.rate_recommendation_run; modify hospitality.rate_recommendation_run; link hospitality.link.restriction_recommendation_for_rate_plan; link hospitality.link.restriction_recommendation_for_room_type; link hospitality.link.restriction_recommendation_at_property; link hospitality.link.restriction_recommendation_part_of_run; link hospitality.link.run_for_property; link hospitality.link.restriction_recommendation_superseded_by.", "operationId": "apply_hospitality_action_recommend_restriction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cadence": { "enum": [ "nightly", "intraday", "hourly", "event_triggered", "manual" ], "title": "Run cadence (used only when opening a fresh run)", "type": "string" }, "closed": { "title": "Recommend a hard stop-sell (defaults to false)", "type": "boolean" }, "closed_to_arrival": { "title": "Recommend closed to arrival (defaults to false)", "type": "boolean" }, "closed_to_departure": { "title": "Recommend closed to departure (defaults to false)", "type": "boolean" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Calibrated probability (optional)", "type": "string" }, "demand_forecast_rooms": { "format": "decimal", "title": "Unconstrained higher-rate demand believed for the first night (rooms)", "type": "string" }, "end_date": { "format": "date", "title": "Last night (inclusive)", "type": "string" }, "expires_at": { "format": "date-time", "title": "Recommendation expiry (default: issued_at + 4h when absent)", "type": "string" }, "expires_on": { "format": "date", "title": "The house business day the recommendation lapses after, in place of `expires_at`: the house's open business date decides expiry, not the wall clock, so a day's recommendations apply on that business day however late it closes", "type": "string" }, "factors_considered": { "items": { "enum": [ "pickup_pace", "booking_curve", "competitive_set", "event_calendar", "historical_pattern", "segment_mix", "channel_mix", "length_of_stay_distribution", "cancellation_rate", "no_show_rate", "package_attachment", "group_displacement", "weather", "other" ], "type": "string" }, "title": "Signals that drove the recommendation", "type": "array" }, "forecast_snapshot": { "additionalProperties": true, "title": "Forecast snapshot (struct as JSON; `forecast_kind` and `as_of` required)", "type": "object" }, "lift": { "title": "Recommend lifting what stands in exactly this scope over the range — the re-open; exclusive with every constraint (defaults to false)", "type": "boolean" }, "max_length_of_stay": { "title": "Recommended maximum length of stay (nights)", "type": "integer" }, "min_length_of_stay": { "title": "Recommended minimum length of stay (nights)", "type": "integer" }, "protection_level": { "title": "Rooms the recommender wants kept for the higher rate", "type": "integer" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan scope (at least one of room_type_id / rate_plan_id)", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "rationale_text": { "title": "Human-readable explanation", "type": "string" }, "room_type_id": { "format": "uuid", "title": "Room type scope (at least one of room_type_id / rate_plan_id)", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "rooms_remaining": { "title": "Rooms left to sell on the first night, at issue time", "type": "integer" }, "run_id": { "title": "Existing run to append to (handler opens one when absent)", "type": "string" }, "sell_up_rate": { "format": "decimal", "title": "Share of fenced-rate buyers believed to pay the higher rate once the fence closes (0..=1)", "type": "string" }, "start_date": { "format": "date", "title": "First night", "type": "string" }, "target_horizon_days": { "title": "Forecast horizon the run looked over (used only when opening a run)", "type": "integer" } }, "required": [ "start_date", "end_date", "confidence", "factors_considered", "rationale_text", "forecast_snapshot" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.restriction_recommendation_for_rate_plan", "hospitality.link.restriction_recommendation_for_room_type", "hospitality.link.restriction_recommendation_at_property", "hospitality.link.restriction_recommendation_part_of_run", "hospitality.link.run_for_property", "hospitality.link.restriction_recommendation_superseded_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.restriction_recommendation", "hospitality.rate_recommendation_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.recommend_restriction:apply" ] } ], "summary": "Recommend restriction", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.recommend_restriction/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_recommend_restriction` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.recommend_restriction:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_recommend_restriction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cadence": { "enum": [ "nightly", "intraday", "hourly", "event_triggered", "manual" ], "title": "Run cadence (used only when opening a fresh run)", "type": "string" }, "closed": { "title": "Recommend a hard stop-sell (defaults to false)", "type": "boolean" }, "closed_to_arrival": { "title": "Recommend closed to arrival (defaults to false)", "type": "boolean" }, "closed_to_departure": { "title": "Recommend closed to departure (defaults to false)", "type": "boolean" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Calibrated probability (optional)", "type": "string" }, "demand_forecast_rooms": { "format": "decimal", "title": "Unconstrained higher-rate demand believed for the first night (rooms)", "type": "string" }, "end_date": { "format": "date", "title": "Last night (inclusive)", "type": "string" }, "expires_at": { "format": "date-time", "title": "Recommendation expiry (default: issued_at + 4h when absent)", "type": "string" }, "expires_on": { "format": "date", "title": "The house business day the recommendation lapses after, in place of `expires_at`: the house's open business date decides expiry, not the wall clock, so a day's recommendations apply on that business day however late it closes", "type": "string" }, "factors_considered": { "items": { "enum": [ "pickup_pace", "booking_curve", "competitive_set", "event_calendar", "historical_pattern", "segment_mix", "channel_mix", "length_of_stay_distribution", "cancellation_rate", "no_show_rate", "package_attachment", "group_displacement", "weather", "other" ], "type": "string" }, "title": "Signals that drove the recommendation", "type": "array" }, "forecast_snapshot": { "additionalProperties": true, "title": "Forecast snapshot (struct as JSON; `forecast_kind` and `as_of` required)", "type": "object" }, "lift": { "title": "Recommend lifting what stands in exactly this scope over the range — the re-open; exclusive with every constraint (defaults to false)", "type": "boolean" }, "max_length_of_stay": { "title": "Recommended maximum length of stay (nights)", "type": "integer" }, "min_length_of_stay": { "title": "Recommended minimum length of stay (nights)", "type": "integer" }, "protection_level": { "title": "Rooms the recommender wants kept for the higher rate", "type": "integer" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan scope (at least one of room_type_id / rate_plan_id)", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "rationale_text": { "title": "Human-readable explanation", "type": "string" }, "room_type_id": { "format": "uuid", "title": "Room type scope (at least one of room_type_id / rate_plan_id)", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "rooms_remaining": { "title": "Rooms left to sell on the first night, at issue time", "type": "integer" }, "run_id": { "title": "Existing run to append to (handler opens one when absent)", "type": "string" }, "sell_up_rate": { "format": "decimal", "title": "Share of fenced-rate buyers believed to pay the higher rate once the fence closes (0..=1)", "type": "string" }, "start_date": { "format": "date", "title": "First night", "type": "string" }, "target_horizon_days": { "title": "Forecast horizon the run looked over (used only when opening a run)", "type": "integer" } }, "required": [ "start_date", "end_date", "confidence", "factors_considered", "rationale_text", "forecast_snapshot" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.restriction_recommendation_for_rate_plan", "hospitality.link.restriction_recommendation_for_room_type", "hospitality.link.restriction_recommendation_at_property", "hospitality.link.restriction_recommendation_part_of_run", "hospitality.link.run_for_property", "hospitality.link.restriction_recommendation_superseded_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.restriction_recommendation", "hospitality.rate_recommendation_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Recommend restriction (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.recommend_restriction/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_recommend_restriction`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_recommend_restriction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cadence": { "enum": [ "nightly", "intraday", "hourly", "event_triggered", "manual" ], "title": "Run cadence (used only when opening a fresh run)", "type": "string" }, "closed": { "title": "Recommend a hard stop-sell (defaults to false)", "type": "boolean" }, "closed_to_arrival": { "title": "Recommend closed to arrival (defaults to false)", "type": "boolean" }, "closed_to_departure": { "title": "Recommend closed to departure (defaults to false)", "type": "boolean" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Calibrated probability (optional)", "type": "string" }, "demand_forecast_rooms": { "format": "decimal", "title": "Unconstrained higher-rate demand believed for the first night (rooms)", "type": "string" }, "end_date": { "format": "date", "title": "Last night (inclusive)", "type": "string" }, "expires_at": { "format": "date-time", "title": "Recommendation expiry (default: issued_at + 4h when absent)", "type": "string" }, "expires_on": { "format": "date", "title": "The house business day the recommendation lapses after, in place of `expires_at`: the house's open business date decides expiry, not the wall clock, so a day's recommendations apply on that business day however late it closes", "type": "string" }, "factors_considered": { "items": { "enum": [ "pickup_pace", "booking_curve", "competitive_set", "event_calendar", "historical_pattern", "segment_mix", "channel_mix", "length_of_stay_distribution", "cancellation_rate", "no_show_rate", "package_attachment", "group_displacement", "weather", "other" ], "type": "string" }, "title": "Signals that drove the recommendation", "type": "array" }, "forecast_snapshot": { "additionalProperties": true, "title": "Forecast snapshot (struct as JSON; `forecast_kind` and `as_of` required)", "type": "object" }, "lift": { "title": "Recommend lifting what stands in exactly this scope over the range — the re-open; exclusive with every constraint (defaults to false)", "type": "boolean" }, "max_length_of_stay": { "title": "Recommended maximum length of stay (nights)", "type": "integer" }, "min_length_of_stay": { "title": "Recommended minimum length of stay (nights)", "type": "integer" }, "protection_level": { "title": "Rooms the recommender wants kept for the higher rate", "type": "integer" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan scope (at least one of room_type_id / rate_plan_id)", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "rationale_text": { "title": "Human-readable explanation", "type": "string" }, "room_type_id": { "format": "uuid", "title": "Room type scope (at least one of room_type_id / rate_plan_id)", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "rooms_remaining": { "title": "Rooms left to sell on the first night, at issue time", "type": "integer" }, "run_id": { "title": "Existing run to append to (handler opens one when absent)", "type": "string" }, "sell_up_rate": { "format": "decimal", "title": "Share of fenced-rate buyers believed to pay the higher rate once the fence closes (0..=1)", "type": "string" }, "start_date": { "format": "date", "title": "First night", "type": "string" }, "target_horizon_days": { "title": "Forecast horizon the run looked over (used only when opening a run)", "type": "integer" } }, "required": [ "start_date", "end_date", "confidence", "factors_considered", "rationale_text", "forecast_snapshot" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Recommend restriction (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.recommend_restriction/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_recommend_restriction` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.recommend_restriction:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_recommend_restriction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cadence": { "enum": [ "nightly", "intraday", "hourly", "event_triggered", "manual" ], "title": "Run cadence (used only when opening a fresh run)", "type": "string" }, "closed": { "title": "Recommend a hard stop-sell (defaults to false)", "type": "boolean" }, "closed_to_arrival": { "title": "Recommend closed to arrival (defaults to false)", "type": "boolean" }, "closed_to_departure": { "title": "Recommend closed to departure (defaults to false)", "type": "boolean" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Calibrated probability (optional)", "type": "string" }, "demand_forecast_rooms": { "format": "decimal", "title": "Unconstrained higher-rate demand believed for the first night (rooms)", "type": "string" }, "end_date": { "format": "date", "title": "Last night (inclusive)", "type": "string" }, "expires_at": { "format": "date-time", "title": "Recommendation expiry (default: issued_at + 4h when absent)", "type": "string" }, "expires_on": { "format": "date", "title": "The house business day the recommendation lapses after, in place of `expires_at`: the house's open business date decides expiry, not the wall clock, so a day's recommendations apply on that business day however late it closes", "type": "string" }, "factors_considered": { "items": { "enum": [ "pickup_pace", "booking_curve", "competitive_set", "event_calendar", "historical_pattern", "segment_mix", "channel_mix", "length_of_stay_distribution", "cancellation_rate", "no_show_rate", "package_attachment", "group_displacement", "weather", "other" ], "type": "string" }, "title": "Signals that drove the recommendation", "type": "array" }, "forecast_snapshot": { "additionalProperties": true, "title": "Forecast snapshot (struct as JSON; `forecast_kind` and `as_of` required)", "type": "object" }, "lift": { "title": "Recommend lifting what stands in exactly this scope over the range — the re-open; exclusive with every constraint (defaults to false)", "type": "boolean" }, "max_length_of_stay": { "title": "Recommended maximum length of stay (nights)", "type": "integer" }, "min_length_of_stay": { "title": "Recommended minimum length of stay (nights)", "type": "integer" }, "protection_level": { "title": "Rooms the recommender wants kept for the higher rate", "type": "integer" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan scope (at least one of room_type_id / rate_plan_id)", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "rationale_text": { "title": "Human-readable explanation", "type": "string" }, "room_type_id": { "format": "uuid", "title": "Room type scope (at least one of room_type_id / rate_plan_id)", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "rooms_remaining": { "title": "Rooms left to sell on the first night, at issue time", "type": "integer" }, "run_id": { "title": "Existing run to append to (handler opens one when absent)", "type": "string" }, "sell_up_rate": { "format": "decimal", "title": "Share of fenced-rate buyers believed to pay the higher rate once the fence closes (0..=1)", "type": "string" }, "start_date": { "format": "date", "title": "First night", "type": "string" }, "target_horizon_days": { "title": "Forecast horizon the run looked over (used only when opening a run)", "type": "integer" } }, "required": [ "start_date", "end_date", "confidence", "factors_considered", "rationale_text", "forecast_snapshot" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Recommend restriction (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.recommend_sell_limit/apply": { "post": { "description": "Emit a typed overbooking recommendation against the target property: for one room type over `start_date..=end_date`, the oversell headroom it may sell past its sellable rooms (`oversell_limit`, at least 0), or `reset` — the explicit return to the operator's declared limit. Exactly one of the two: a recommendation states the limit, absence never means reset. The reading behind it — the rooms on the books, the share believed to arrive, the walk cost and the marginal rate the limit balances, the walks expected at it — and the forecast snapshot are frozen at issue as a `sell_limit_recommendation` in `suggested` state; a still-suggested prior for the same room type and range is superseded. Decision lifecycle flows through `apply_sell_limit_recommendation` / `reject_sell_limit_recommendation` / `expire_sell_limit_recommendations`. Joins an in-progress `rate_recommendation_run` when `run_id` is given and opens one otherwise.\n\nEffects: create hospitality.sell_limit_recommendation; modify hospitality.sell_limit_recommendation; create hospitality.rate_recommendation_run; modify hospitality.rate_recommendation_run; link hospitality.link.sell_limit_recommendation_for_room_type; link hospitality.link.sell_limit_recommendation_at_property; link hospitality.link.sell_limit_recommendation_part_of_run; link hospitality.link.run_for_property; link hospitality.link.sell_limit_recommendation_superseded_by.", "operationId": "apply_hospitality_action_recommend_sell_limit", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cadence": { "enum": [ "nightly", "intraday", "hourly", "event_triggered", "manual" ], "title": "Run cadence (used only when opening a fresh run)", "type": "string" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Calibrated probability (optional)", "type": "string" }, "end_date": { "format": "date", "title": "Last night (inclusive)", "type": "string" }, "expected_walks": { "description": "Guests expected to be walked on the first night at the limit", "format": "decimal", "title": "Expected walks", "type": "string" }, "expires_at": { "format": "date-time", "title": "Recommendation expiry (default: issued_at + 4h when absent)", "type": "string" }, "expires_on": { "format": "date", "title": "The house business day the recommendation lapses after, in place of `expires_at`: the house's open business date decides expiry, not the wall clock, so a day's recommendations apply on that business day however late it closes", "type": "string" }, "factors_considered": { "items": { "enum": [ "pickup_pace", "booking_curve", "competitive_set", "event_calendar", "historical_pattern", "segment_mix", "channel_mix", "length_of_stay_distribution", "cancellation_rate", "no_show_rate", "package_attachment", "group_displacement", "weather", "other" ], "type": "string" }, "title": "Signals that drove the recommendation", "type": "array" }, "forecast_snapshot": { "additionalProperties": true, "title": "Forecast snapshot (struct as JSON; `forecast_kind` and `as_of` required)", "type": "object" }, "marginal_rate": { "description": "The nightly rate one more sale on the first night would earn", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Marginal rate", "type": "object" }, "oversell_limit": { "description": "Recommended oversell headroom over the sellable rooms (rooms, at least 0); exclusive with `reset`", "title": "Oversell limit", "type": "integer" }, "rationale_text": { "title": "Human-readable explanation", "type": "string" }, "reset": { "description": "Recommend returning to the operator's declared limit; exclusive with `oversell_limit` (defaults to false)", "title": "Reset", "type": "boolean" }, "room_type_id": { "description": "The room type whose availability ledger the limit would move", "format": "uuid", "title": "Room type", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "rooms_on_books": { "description": "Rooms of the type on the books for the first night, at issue time", "title": "Rooms on books", "type": "integer" }, "run_id": { "title": "Existing run to append to (handler opens one when absent)", "type": "string" }, "show_rate": { "description": "Share of the rooms on the books believed to arrive (0..=1)", "format": "decimal", "title": "Show rate", "type": "string" }, "start_date": { "format": "date", "title": "First night", "type": "string" }, "target_horizon_days": { "title": "Forecast horizon the run looked over (used only when opening a run)", "type": "integer" }, "walk_cost": { "description": "What walking one arriving guest is believed to cost, past the night's own revenue", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Walk cost", "type": "object" } }, "required": [ "room_type_id", "start_date", "end_date", "confidence", "factors_considered", "rationale_text", "forecast_snapshot" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.sell_limit_recommendation_for_room_type", "hospitality.link.sell_limit_recommendation_at_property", "hospitality.link.sell_limit_recommendation_part_of_run", "hospitality.link.run_for_property", "hospitality.link.sell_limit_recommendation_superseded_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.sell_limit_recommendation", "hospitality.rate_recommendation_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.recommend_sell_limit:apply" ] } ], "summary": "Recommend sell limit", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.recommend_sell_limit/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_recommend_sell_limit` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.recommend_sell_limit:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_recommend_sell_limit", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cadence": { "enum": [ "nightly", "intraday", "hourly", "event_triggered", "manual" ], "title": "Run cadence (used only when opening a fresh run)", "type": "string" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Calibrated probability (optional)", "type": "string" }, "end_date": { "format": "date", "title": "Last night (inclusive)", "type": "string" }, "expected_walks": { "description": "Guests expected to be walked on the first night at the limit", "format": "decimal", "title": "Expected walks", "type": "string" }, "expires_at": { "format": "date-time", "title": "Recommendation expiry (default: issued_at + 4h when absent)", "type": "string" }, "expires_on": { "format": "date", "title": "The house business day the recommendation lapses after, in place of `expires_at`: the house's open business date decides expiry, not the wall clock, so a day's recommendations apply on that business day however late it closes", "type": "string" }, "factors_considered": { "items": { "enum": [ "pickup_pace", "booking_curve", "competitive_set", "event_calendar", "historical_pattern", "segment_mix", "channel_mix", "length_of_stay_distribution", "cancellation_rate", "no_show_rate", "package_attachment", "group_displacement", "weather", "other" ], "type": "string" }, "title": "Signals that drove the recommendation", "type": "array" }, "forecast_snapshot": { "additionalProperties": true, "title": "Forecast snapshot (struct as JSON; `forecast_kind` and `as_of` required)", "type": "object" }, "marginal_rate": { "description": "The nightly rate one more sale on the first night would earn", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Marginal rate", "type": "object" }, "oversell_limit": { "description": "Recommended oversell headroom over the sellable rooms (rooms, at least 0); exclusive with `reset`", "title": "Oversell limit", "type": "integer" }, "rationale_text": { "title": "Human-readable explanation", "type": "string" }, "reset": { "description": "Recommend returning to the operator's declared limit; exclusive with `oversell_limit` (defaults to false)", "title": "Reset", "type": "boolean" }, "room_type_id": { "description": "The room type whose availability ledger the limit would move", "format": "uuid", "title": "Room type", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "rooms_on_books": { "description": "Rooms of the type on the books for the first night, at issue time", "title": "Rooms on books", "type": "integer" }, "run_id": { "title": "Existing run to append to (handler opens one when absent)", "type": "string" }, "show_rate": { "description": "Share of the rooms on the books believed to arrive (0..=1)", "format": "decimal", "title": "Show rate", "type": "string" }, "start_date": { "format": "date", "title": "First night", "type": "string" }, "target_horizon_days": { "title": "Forecast horizon the run looked over (used only when opening a run)", "type": "integer" }, "walk_cost": { "description": "What walking one arriving guest is believed to cost, past the night's own revenue", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Walk cost", "type": "object" } }, "required": [ "room_type_id", "start_date", "end_date", "confidence", "factors_considered", "rationale_text", "forecast_snapshot" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.sell_limit_recommendation_for_room_type", "hospitality.link.sell_limit_recommendation_at_property", "hospitality.link.sell_limit_recommendation_part_of_run", "hospitality.link.run_for_property", "hospitality.link.sell_limit_recommendation_superseded_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.sell_limit_recommendation", "hospitality.rate_recommendation_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Recommend sell limit (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.recommend_sell_limit/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_recommend_sell_limit`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_recommend_sell_limit", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cadence": { "enum": [ "nightly", "intraday", "hourly", "event_triggered", "manual" ], "title": "Run cadence (used only when opening a fresh run)", "type": "string" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Calibrated probability (optional)", "type": "string" }, "end_date": { "format": "date", "title": "Last night (inclusive)", "type": "string" }, "expected_walks": { "description": "Guests expected to be walked on the first night at the limit", "format": "decimal", "title": "Expected walks", "type": "string" }, "expires_at": { "format": "date-time", "title": "Recommendation expiry (default: issued_at + 4h when absent)", "type": "string" }, "expires_on": { "format": "date", "title": "The house business day the recommendation lapses after, in place of `expires_at`: the house's open business date decides expiry, not the wall clock, so a day's recommendations apply on that business day however late it closes", "type": "string" }, "factors_considered": { "items": { "enum": [ "pickup_pace", "booking_curve", "competitive_set", "event_calendar", "historical_pattern", "segment_mix", "channel_mix", "length_of_stay_distribution", "cancellation_rate", "no_show_rate", "package_attachment", "group_displacement", "weather", "other" ], "type": "string" }, "title": "Signals that drove the recommendation", "type": "array" }, "forecast_snapshot": { "additionalProperties": true, "title": "Forecast snapshot (struct as JSON; `forecast_kind` and `as_of` required)", "type": "object" }, "marginal_rate": { "description": "The nightly rate one more sale on the first night would earn", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Marginal rate", "type": "object" }, "oversell_limit": { "description": "Recommended oversell headroom over the sellable rooms (rooms, at least 0); exclusive with `reset`", "title": "Oversell limit", "type": "integer" }, "rationale_text": { "title": "Human-readable explanation", "type": "string" }, "reset": { "description": "Recommend returning to the operator's declared limit; exclusive with `oversell_limit` (defaults to false)", "title": "Reset", "type": "boolean" }, "room_type_id": { "description": "The room type whose availability ledger the limit would move", "format": "uuid", "title": "Room type", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "rooms_on_books": { "description": "Rooms of the type on the books for the first night, at issue time", "title": "Rooms on books", "type": "integer" }, "run_id": { "title": "Existing run to append to (handler opens one when absent)", "type": "string" }, "show_rate": { "description": "Share of the rooms on the books believed to arrive (0..=1)", "format": "decimal", "title": "Show rate", "type": "string" }, "start_date": { "format": "date", "title": "First night", "type": "string" }, "target_horizon_days": { "title": "Forecast horizon the run looked over (used only when opening a run)", "type": "integer" }, "walk_cost": { "description": "What walking one arriving guest is believed to cost, past the night's own revenue", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Walk cost", "type": "object" } }, "required": [ "room_type_id", "start_date", "end_date", "confidence", "factors_considered", "rationale_text", "forecast_snapshot" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Recommend sell limit (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.recommend_sell_limit/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_recommend_sell_limit` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.recommend_sell_limit:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_recommend_sell_limit", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cadence": { "enum": [ "nightly", "intraday", "hourly", "event_triggered", "manual" ], "title": "Run cadence (used only when opening a fresh run)", "type": "string" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Calibrated probability (optional)", "type": "string" }, "end_date": { "format": "date", "title": "Last night (inclusive)", "type": "string" }, "expected_walks": { "description": "Guests expected to be walked on the first night at the limit", "format": "decimal", "title": "Expected walks", "type": "string" }, "expires_at": { "format": "date-time", "title": "Recommendation expiry (default: issued_at + 4h when absent)", "type": "string" }, "expires_on": { "format": "date", "title": "The house business day the recommendation lapses after, in place of `expires_at`: the house's open business date decides expiry, not the wall clock, so a day's recommendations apply on that business day however late it closes", "type": "string" }, "factors_considered": { "items": { "enum": [ "pickup_pace", "booking_curve", "competitive_set", "event_calendar", "historical_pattern", "segment_mix", "channel_mix", "length_of_stay_distribution", "cancellation_rate", "no_show_rate", "package_attachment", "group_displacement", "weather", "other" ], "type": "string" }, "title": "Signals that drove the recommendation", "type": "array" }, "forecast_snapshot": { "additionalProperties": true, "title": "Forecast snapshot (struct as JSON; `forecast_kind` and `as_of` required)", "type": "object" }, "marginal_rate": { "description": "The nightly rate one more sale on the first night would earn", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Marginal rate", "type": "object" }, "oversell_limit": { "description": "Recommended oversell headroom over the sellable rooms (rooms, at least 0); exclusive with `reset`", "title": "Oversell limit", "type": "integer" }, "rationale_text": { "title": "Human-readable explanation", "type": "string" }, "reset": { "description": "Recommend returning to the operator's declared limit; exclusive with `oversell_limit` (defaults to false)", "title": "Reset", "type": "boolean" }, "room_type_id": { "description": "The room type whose availability ledger the limit would move", "format": "uuid", "title": "Room type", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "rooms_on_books": { "description": "Rooms of the type on the books for the first night, at issue time", "title": "Rooms on books", "type": "integer" }, "run_id": { "title": "Existing run to append to (handler opens one when absent)", "type": "string" }, "show_rate": { "description": "Share of the rooms on the books believed to arrive (0..=1)", "format": "decimal", "title": "Show rate", "type": "string" }, "start_date": { "format": "date", "title": "First night", "type": "string" }, "target_horizon_days": { "title": "Forecast horizon the run looked over (used only when opening a run)", "type": "integer" }, "walk_cost": { "description": "What walking one arriving guest is believed to cost, past the night's own revenue", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Walk cost", "type": "object" } }, "required": [ "room_type_id", "start_date", "end_date", "confidence", "factors_considered", "rationale_text", "forecast_snapshot" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Recommend sell limit (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.reconcile_folio_balance/apply": { "post": { "description": "Recompute the folio's balance from its own lines — the balance brought forward, plus every unvoided, non-package charge at what it debited (base + exclusive tax + gratuity), less every settled payment and refunded leg — and write it back only when the stored figure disagrees, emitting `folio.balance_reconciled.recorded` with the delta and a `reconcile` ledger entry dated today, so drift is observable and a closed day is never rewritten. A folio not yet on the ledger (an import, a row older than the ledger) is brought onto it first with an `opening` entry for its whole balance. Idempotent: a folio that agrees with its lines is left untouched.\n\nEffects: modify hospitality.folio.", "operationId": "apply_hospitality_action_reconcile_folio_balance", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.reconcile_folio_balance:apply" ] } ], "summary": "Reconcile folio balance", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.reconcile_folio_balance/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_reconcile_folio_balance` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.reconcile_folio_balance:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_reconcile_folio_balance", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Reconcile folio balance (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.reconcile_folio_balance/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_reconcile_folio_balance`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_reconcile_folio_balance", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Reconcile folio balance (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.reconcile_folio_balance/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_reconcile_folio_balance` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.reconcile_folio_balance:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_reconcile_folio_balance", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Reconcile folio balance (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.record_assessment/apply": { "post": { "description": "Record a longevity assessment binding for the target membership. Creates a `longevity_assessment` row (no clinical detail in payload — structural contract per commit 5) and links it to the mandatory `external_record_reference` that holds the actual record. The HIPAA / GDPR Article 9 boundary is structural: Aerandil holds only the opaque pointer.\n\nEffects: create hospitality.longevity_assessment; link hospitality.link.assessment_for_membership; link hospitality.link.assessment_references_external_record.", "operationId": "apply_hospitality_action_record_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "assessed_at": { "format": "date-time", "title": "When the assessment was administered", "type": "string" }, "external_record_reference_id": { "format": "uuid", "title": "External clinical-record reference (mandatory clinical seam)", "type": "string", "x-aerandil-references": "hospitality.external_record_reference" }, "summary_tags": { "items": { "type": "string" }, "title": "Operator-defined tags (no clinical detail)", "type": "array" } }, "required": [ "external_record_reference_id", "assessed_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.assessment_for_membership", "hospitality.link.assessment_references_external_record" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.longevity_assessment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_assessment:apply" ] } ], "summary": "Record assessment", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.record_assessment/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_assessment` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_assessment:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "assessed_at": { "format": "date-time", "title": "When the assessment was administered", "type": "string" }, "external_record_reference_id": { "format": "uuid", "title": "External clinical-record reference (mandatory clinical seam)", "type": "string", "x-aerandil-references": "hospitality.external_record_reference" }, "summary_tags": { "items": { "type": "string" }, "title": "Operator-defined tags (no clinical detail)", "type": "array" } }, "required": [ "external_record_reference_id", "assessed_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.assessment_for_membership", "hospitality.link.assessment_references_external_record" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.longevity_assessment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record assessment (dry-run)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.record_assessment/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_assessment`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "assessed_at": { "format": "date-time", "title": "When the assessment was administered", "type": "string" }, "external_record_reference_id": { "format": "uuid", "title": "External clinical-record reference (mandatory clinical seam)", "type": "string", "x-aerandil-references": "hospitality.external_record_reference" }, "summary_tags": { "items": { "type": "string" }, "title": "Operator-defined tags (no clinical detail)", "type": "array" } }, "required": [ "external_record_reference_id", "assessed_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record assessment (dry-run)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.record_assessment/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_assessment` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_assessment:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "assessed_at": { "format": "date-time", "title": "When the assessment was administered", "type": "string" }, "external_record_reference_id": { "format": "uuid", "title": "External clinical-record reference (mandatory clinical seam)", "type": "string", "x-aerandil-references": "hospitality.external_record_reference" }, "summary_tags": { "items": { "type": "string" }, "title": "Operator-defined tags (no clinical detail)", "type": "array" } }, "required": [ "external_record_reference_id", "assessed_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record assessment (rollup delta)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.record_booking_origin/apply": { "post": { "description": "Record the IP address and device a guest booked from, for a booking they made online themselves. Called by the booking engine at booking time; the chargeback evidence packet reads it to argue a fraud claim under Visa Compelling Evidence 3.0. Refuses any booking whose `source` is not `direct_web`: an OTA booking carries no guest IP, and a desk-keyed card would record the hotel's own. Refuses an address that does not parse as IPv4 or IPv6. A replay with the same values is a no-op; a second origin that disagrees with the first is refused rather than overwriting evidence. Stamps `retain_until` as captured_at plus 485 days.\n\nEffects: create hospitality.booking_origin; link hospitality.link.booking_origin_for_reservation.", "operationId": "apply_hospitality_action_record_booking_origin", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "captured_at": { "format": "date-time", "title": "When the guest booked", "type": "string" }, "device_id": { "title": "The booking engine's identifier for the device", "type": "string" }, "ip_address": { "title": "The IP address the booking was made from", "type": "string" } }, "required": [ "ip_address", "captured_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.booking_origin_for_reservation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.booking_origin" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_booking_origin:apply" ] } ], "summary": "Record booking origin", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.record_booking_origin/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_booking_origin` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_booking_origin:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_booking_origin", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "captured_at": { "format": "date-time", "title": "When the guest booked", "type": "string" }, "device_id": { "title": "The booking engine's identifier for the device", "type": "string" }, "ip_address": { "title": "The IP address the booking was made from", "type": "string" } }, "required": [ "ip_address", "captured_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.booking_origin_for_reservation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.booking_origin" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record booking origin (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.record_booking_origin/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_booking_origin`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_booking_origin", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "captured_at": { "format": "date-time", "title": "When the guest booked", "type": "string" }, "device_id": { "title": "The booking engine's identifier for the device", "type": "string" }, "ip_address": { "title": "The IP address the booking was made from", "type": "string" } }, "required": [ "ip_address", "captured_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record booking origin (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.record_booking_origin/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_booking_origin` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_booking_origin:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_booking_origin", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "captured_at": { "format": "date-time", "title": "When the guest booked", "type": "string" }, "device_id": { "title": "The booking engine's identifier for the device", "type": "string" }, "ip_address": { "title": "The IP address the booking was made from", "type": "string" } }, "required": [ "ip_address", "captured_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record booking origin (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.record_brand_operator_cost/apply": { "post": { "description": "Post one mandatory brand/operator charge (USALI 12 Schedule 16) — only mandatory fees; optional services and pass-throughs are excluded by the schedule's definition. Fee computation stays in the agreement's system of record. `external_ref` is the idempotency anchor for invoice imports. Emits `brand_operator.cost.recorded` for the `daily_brand_operator` projection.\n\nEffects: create hospitality.brand_operator_cost_entry; link hospitality.link.brand_operator_cost_at_property; link hospitality.link.brand_operator_cost_for_company.", "operationId": "apply_hospitality_action_record_brand_operator_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "business_date": { "format": "date", "title": "Accrual business date", "type": "string" }, "company_id": { "format": "uuid", "title": "Payee company (optional)", "type": "string", "x-aerandil-references": "hospitality.company" }, "counterparty": { "enum": [ "brand", "operator" ], "title": "Counterparty (brand | operator)", "type": "string" }, "external_ref": { "title": "Invoice-line id (idempotency anchor)", "type": "string" }, "kind": { "enum": [ "royalty_fee", "brand_marketing_assessment", "loyalty_program_fee", "reservation_fee", "technology_fee", "training_fee", "purchasing_program_fee", "payroll_hr_services_fee", "quality_assurance_fee", "base_management_fee", "incentive_management_fee", "other_mandatory_cost" ], "title": "USALI Schedule 16 line", "type": "string" }, "period_end": { "format": "date", "title": "Invoice-period end (optional)", "type": "string" }, "period_start": { "format": "date", "title": "Invoice-period start (optional)", "type": "string" }, "source": { "enum": [ "invoice_import", "manual" ], "title": "Provenance (defaults to `invoice_import`)", "type": "string" } }, "required": [ "kind", "counterparty", "amount", "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.brand_operator_cost_at_property", "hospitality.link.brand_operator_cost_for_company" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.brand_operator_cost_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_brand_operator_cost:apply" ] } ], "summary": "Record brand/operator cost", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_brand_operator_cost/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_brand_operator_cost` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_brand_operator_cost:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_brand_operator_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "business_date": { "format": "date", "title": "Accrual business date", "type": "string" }, "company_id": { "format": "uuid", "title": "Payee company (optional)", "type": "string", "x-aerandil-references": "hospitality.company" }, "counterparty": { "enum": [ "brand", "operator" ], "title": "Counterparty (brand | operator)", "type": "string" }, "external_ref": { "title": "Invoice-line id (idempotency anchor)", "type": "string" }, "kind": { "enum": [ "royalty_fee", "brand_marketing_assessment", "loyalty_program_fee", "reservation_fee", "technology_fee", "training_fee", "purchasing_program_fee", "payroll_hr_services_fee", "quality_assurance_fee", "base_management_fee", "incentive_management_fee", "other_mandatory_cost" ], "title": "USALI Schedule 16 line", "type": "string" }, "period_end": { "format": "date", "title": "Invoice-period end (optional)", "type": "string" }, "period_start": { "format": "date", "title": "Invoice-period start (optional)", "type": "string" }, "source": { "enum": [ "invoice_import", "manual" ], "title": "Provenance (defaults to `invoice_import`)", "type": "string" } }, "required": [ "kind", "counterparty", "amount", "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.brand_operator_cost_at_property", "hospitality.link.brand_operator_cost_for_company" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.brand_operator_cost_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record brand/operator cost (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_brand_operator_cost/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_brand_operator_cost`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_brand_operator_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "business_date": { "format": "date", "title": "Accrual business date", "type": "string" }, "company_id": { "format": "uuid", "title": "Payee company (optional)", "type": "string", "x-aerandil-references": "hospitality.company" }, "counterparty": { "enum": [ "brand", "operator" ], "title": "Counterparty (brand | operator)", "type": "string" }, "external_ref": { "title": "Invoice-line id (idempotency anchor)", "type": "string" }, "kind": { "enum": [ "royalty_fee", "brand_marketing_assessment", "loyalty_program_fee", "reservation_fee", "technology_fee", "training_fee", "purchasing_program_fee", "payroll_hr_services_fee", "quality_assurance_fee", "base_management_fee", "incentive_management_fee", "other_mandatory_cost" ], "title": "USALI Schedule 16 line", "type": "string" }, "period_end": { "format": "date", "title": "Invoice-period end (optional)", "type": "string" }, "period_start": { "format": "date", "title": "Invoice-period start (optional)", "type": "string" }, "source": { "enum": [ "invoice_import", "manual" ], "title": "Provenance (defaults to `invoice_import`)", "type": "string" } }, "required": [ "kind", "counterparty", "amount", "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record brand/operator cost (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_brand_operator_cost/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_brand_operator_cost` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_brand_operator_cost:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_brand_operator_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "business_date": { "format": "date", "title": "Accrual business date", "type": "string" }, "company_id": { "format": "uuid", "title": "Payee company (optional)", "type": "string", "x-aerandil-references": "hospitality.company" }, "counterparty": { "enum": [ "brand", "operator" ], "title": "Counterparty (brand | operator)", "type": "string" }, "external_ref": { "title": "Invoice-line id (idempotency anchor)", "type": "string" }, "kind": { "enum": [ "royalty_fee", "brand_marketing_assessment", "loyalty_program_fee", "reservation_fee", "technology_fee", "training_fee", "purchasing_program_fee", "payroll_hr_services_fee", "quality_assurance_fee", "base_management_fee", "incentive_management_fee", "other_mandatory_cost" ], "title": "USALI Schedule 16 line", "type": "string" }, "period_end": { "format": "date", "title": "Invoice-period end (optional)", "type": "string" }, "period_start": { "format": "date", "title": "Invoice-period start (optional)", "type": "string" }, "source": { "enum": [ "invoice_import", "manual" ], "title": "Provenance (defaults to `invoice_import`)", "type": "string" } }, "required": [ "kind", "counterparty", "amount", "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record brand/operator cost (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_breakfast_taken/apply": { "post": { "description": "The breakfast roster's tick-off: `covers` of the target in-house stay took the breakfast their package includes, with no bill. The stay's breakfast is the first component (by the package's order) of a live package sale whose frozen `daypart` is `breakfast` or `brunch`, eaten at `outlet_id` — one of its alternate outlets, or any outlet of the house when it names none — and due on `business_date` (default: the house's hotel date): a breakfast is eaten the morning after the night that carries it, so the first morning of a stay has none and the departure morning does. `covers` is how many of the room have taken it so far that day, at most the covers the package feeds (the room's adults for a per-adult allowance, everyone in it otherwise): the same number again is a no-op, a lower one is refused, a higher one records the new covers. Each records a `package_component_consumption` through the one package write `consume_package_component` uses — consumed equal to the allowance it draws (`consumed`), the covers' share of the day's allowance, the last cover taking what is left — with its balance-neutral package line on the stay's guest folio at the outlet, and the package ledger's movements. Refused when the stay has no breakfast that day at this outlet, or when the day's allowance is already used up (a room charge may have consumed it). Emits `fnb.breakfast_taken`.\n\nEffects: create hospitality.package_component_consumption; create hospitality.charge; modify hospitality.package_sale; link hospitality.link.package_sale_has_consumption; link hospitality.link.consumption_for_charge; link hospitality.link.folio_has_charge; link hospitality.link.charge_attributed_to_package_sale; link hospitality.link.charge_attributed_to_package_component; link hospitality.link.charge_at_outlet.", "operationId": "apply_hospitality_action_record_breakfast_taken", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date of the breakfast (defaults to the house's hotel date)", "type": "string" }, "covers": { "title": "How many of the room have taken breakfast so far today", "type": "integer" }, "outlet_id": { "format": "uuid", "title": "Outlet the breakfast was taken at", "type": "string", "x-aerandil-references": "hospitality.outlet" } }, "required": [ "outlet_id", "covers" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.package_sale_has_consumption", "hospitality.link.consumption_for_charge", "hospitality.link.folio_has_charge", "hospitality.link.charge_attributed_to_package_sale", "hospitality.link.charge_attributed_to_package_component", "hospitality.link.charge_at_outlet" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.package_component_consumption", "hospitality.charge", "hospitality.package_sale" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_breakfast_taken:apply" ] } ], "summary": "Record breakfast taken", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.record_breakfast_taken/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_breakfast_taken` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_breakfast_taken:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_breakfast_taken", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date of the breakfast (defaults to the house's hotel date)", "type": "string" }, "covers": { "title": "How many of the room have taken breakfast so far today", "type": "integer" }, "outlet_id": { "format": "uuid", "title": "Outlet the breakfast was taken at", "type": "string", "x-aerandil-references": "hospitality.outlet" } }, "required": [ "outlet_id", "covers" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.package_sale_has_consumption", "hospitality.link.consumption_for_charge", "hospitality.link.folio_has_charge", "hospitality.link.charge_attributed_to_package_sale", "hospitality.link.charge_attributed_to_package_component", "hospitality.link.charge_at_outlet" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.package_component_consumption", "hospitality.charge", "hospitality.package_sale" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record breakfast taken (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.record_breakfast_taken/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_breakfast_taken`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_breakfast_taken", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date of the breakfast (defaults to the house's hotel date)", "type": "string" }, "covers": { "title": "How many of the room have taken breakfast so far today", "type": "integer" }, "outlet_id": { "format": "uuid", "title": "Outlet the breakfast was taken at", "type": "string", "x-aerandil-references": "hospitality.outlet" } }, "required": [ "outlet_id", "covers" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record breakfast taken (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.record_breakfast_taken/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_breakfast_taken` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_breakfast_taken:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_breakfast_taken", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date of the breakfast (defaults to the house's hotel date)", "type": "string" }, "covers": { "title": "How many of the room have taken breakfast so far today", "type": "integer" }, "outlet_id": { "format": "uuid", "title": "Outlet the breakfast was taken at", "type": "string", "x-aerandil-references": "hospitality.outlet" } }, "required": [ "outlet_id", "covers" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record breakfast taken (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.record_cashier_transaction/apply": { "post": { "description": "Record one typed cash movement in an open session — cash_in, cash_out, tip_out, expense (the paid-out), or float_adjustment. Amounts are positive; the kind carries the direction. Append-only: a mistake is cancelled by a compensating entry, never an edit or a void. Pass payment_id when the movement mirrors a folio cash payment — the payment stays the ledger truth, the session entry reconciles the physical drawer.\n\nEffects: create hospitality.cashier_transaction; link hospitality.link.cashier_transaction_in_session; link hospitality.link.cashier_transaction_mirrors_payment.", "operationId": "apply_hospitality_action_record_cashier_transaction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "kind": { "enum": [ "cash_in", "cash_out", "tip_out", "expense", "float_adjustment" ], "title": "Movement kind", "type": "string" }, "notes": { "title": "Reason for the movement", "type": "string" }, "occurred_at": { "format": "date-time", "title": "When the cash moved (business time; defaults to now)", "type": "string" }, "payment_id": { "format": "uuid", "title": "The folio payment this movement mirrors, if any", "type": "string", "x-aerandil-references": "hospitality.payment" } }, "required": [ "kind", "amount" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.cashier_session" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.cashier_transaction_in_session", "hospitality.link.cashier_transaction_mirrors_payment" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.cashier_transaction" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_cashier_transaction:apply" ] } ], "summary": "Record cashier transaction", "tags": [ "cashiering" ] } }, "/v1/actions/hospitality.action.record_cashier_transaction/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_cashier_transaction` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_cashier_transaction:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_cashier_transaction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "kind": { "enum": [ "cash_in", "cash_out", "tip_out", "expense", "float_adjustment" ], "title": "Movement kind", "type": "string" }, "notes": { "title": "Reason for the movement", "type": "string" }, "occurred_at": { "format": "date-time", "title": "When the cash moved (business time; defaults to now)", "type": "string" }, "payment_id": { "format": "uuid", "title": "The folio payment this movement mirrors, if any", "type": "string", "x-aerandil-references": "hospitality.payment" } }, "required": [ "kind", "amount" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.cashier_session" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.cashier_transaction_in_session", "hospitality.link.cashier_transaction_mirrors_payment" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.cashier_transaction" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record cashier transaction (dry-run)", "tags": [ "cashiering" ] } }, "/v1/actions/hospitality.action.record_cashier_transaction/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_cashier_transaction`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_cashier_transaction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "kind": { "enum": [ "cash_in", "cash_out", "tip_out", "expense", "float_adjustment" ], "title": "Movement kind", "type": "string" }, "notes": { "title": "Reason for the movement", "type": "string" }, "occurred_at": { "format": "date-time", "title": "When the cash moved (business time; defaults to now)", "type": "string" }, "payment_id": { "format": "uuid", "title": "The folio payment this movement mirrors, if any", "type": "string", "x-aerandil-references": "hospitality.payment" } }, "required": [ "kind", "amount" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.cashier_session" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record cashier transaction (dry-run)", "tags": [ "cashiering" ] } }, "/v1/actions/hospitality.action.record_cashier_transaction/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_cashier_transaction` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_cashier_transaction:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_cashier_transaction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "kind": { "enum": [ "cash_in", "cash_out", "tip_out", "expense", "float_adjustment" ], "title": "Movement kind", "type": "string" }, "notes": { "title": "Reason for the movement", "type": "string" }, "occurred_at": { "format": "date-time", "title": "When the cash moved (business time; defaults to now)", "type": "string" }, "payment_id": { "format": "uuid", "title": "The folio payment this movement mirrors, if any", "type": "string", "x-aerandil-references": "hospitality.payment" } }, "required": [ "kind", "amount" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.cashier_session" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record cashier transaction (rollup delta)", "tags": [ "cashiering" ] } }, "/v1/actions/hospitality.action.record_checklist_result/apply": { "post": { "description": "Record the ticked checklist against a housekeeping task — the attendant's list at a clean, the supervisor's at an inspection. The template is `template_id`, or (absent) the most specific active template for the task's type and room type; a named template must apply to the task. `items` answer the template's items by `code` (each at most once; a code the template does not have refuses; a `count` item's `value` is a whole number); the `score` is derived — the template's `check` items answered ok ÷ all its `check` items, × 100, rounded half up (none when the template has no checks). The recorder is the staff member behind the session, taken from the principal as `start_housekeeping_task` self-assigns. One write, replay-safe per task × template: an identical repeat writes nothing, even once the task is finished or its template retired or revised; different answers replace this task's earlier result in place while the task is open; a complete or skipped task refuses. Photos attach to the result (`host_kind = checklist_result`). Emits `checklist_result.recorded`.\n\nEffects: create hospitality.checklist_result; modify hospitality.checklist_result; link hospitality.link.checklist_result_for_task; link hospitality.link.checklist_result_for_template; link hospitality.link.checklist_result_recorded_by; unlink hospitality.link.checklist_result_recorded_by.", "operationId": "apply_hospitality_action_record_checklist_result", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "items": { "items": { "properties": { "code": { "type": "string" }, "ok": { "type": "boolean" }, "remark": { "type": "string" }, "value": { "type": "string" } }, "required": [ "code", "ok" ], "type": "object" }, "title": "Checked items", "type": "array" }, "recorded_at": { "format": "date-time", "title": "When the list was ticked (defaults to now)", "type": "string" }, "remarks": { "title": "Remarks on the whole list", "type": "string" }, "template_id": { "format": "uuid", "title": "The template answered (absent: the one that resolves for the task)", "type": "string", "x-aerandil-references": "hospitality.checklist_template" } }, "required": [ "items" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.checklist_result_for_task", "hospitality.link.checklist_result_for_template", "hospitality.link.checklist_result_recorded_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.checklist_result" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_checklist_result:apply" ] } ], "summary": "Record checklist result", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.record_checklist_result/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_checklist_result` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_checklist_result:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_checklist_result", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "items": { "items": { "properties": { "code": { "type": "string" }, "ok": { "type": "boolean" }, "remark": { "type": "string" }, "value": { "type": "string" } }, "required": [ "code", "ok" ], "type": "object" }, "title": "Checked items", "type": "array" }, "recorded_at": { "format": "date-time", "title": "When the list was ticked (defaults to now)", "type": "string" }, "remarks": { "title": "Remarks on the whole list", "type": "string" }, "template_id": { "format": "uuid", "title": "The template answered (absent: the one that resolves for the task)", "type": "string", "x-aerandil-references": "hospitality.checklist_template" } }, "required": [ "items" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.checklist_result_for_task", "hospitality.link.checklist_result_for_template", "hospitality.link.checklist_result_recorded_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.checklist_result" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record checklist result (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.record_checklist_result/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_checklist_result`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_checklist_result", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "items": { "items": { "properties": { "code": { "type": "string" }, "ok": { "type": "boolean" }, "remark": { "type": "string" }, "value": { "type": "string" } }, "required": [ "code", "ok" ], "type": "object" }, "title": "Checked items", "type": "array" }, "recorded_at": { "format": "date-time", "title": "When the list was ticked (defaults to now)", "type": "string" }, "remarks": { "title": "Remarks on the whole list", "type": "string" }, "template_id": { "format": "uuid", "title": "The template answered (absent: the one that resolves for the task)", "type": "string", "x-aerandil-references": "hospitality.checklist_template" } }, "required": [ "items" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record checklist result (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.record_checklist_result/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_checklist_result` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_checklist_result:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_checklist_result", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "items": { "items": { "properties": { "code": { "type": "string" }, "ok": { "type": "boolean" }, "remark": { "type": "string" }, "value": { "type": "string" } }, "required": [ "code", "ok" ], "type": "object" }, "title": "Checked items", "type": "array" }, "recorded_at": { "format": "date-time", "title": "When the list was ticked (defaults to now)", "type": "string" }, "remarks": { "title": "Remarks on the whole list", "type": "string" }, "template_id": { "format": "uuid", "title": "The template answered (absent: the one that resolves for the task)", "type": "string", "x-aerandil-references": "hospitality.checklist_template" } }, "required": [ "items" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record checklist result (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.record_checkpoint/apply": { "post": { "description": "Record one checkpoint of an open round — hubOS's 'submit checkpoint'. `position` names the checkpoint in the round's own list; `items` answer its items by `code` (each at most once; a code it does not have refuses): a `check` needs `ok`, a `reading` its `value`, a `text` its `text`, a `photo` nothing (its photo attaches to the result), a `section` heading takes no answer, and any item may say `ok: false`. A reading with limits that the walker does not judge is judged by them: ok within `min` / `max`, an anomaly outside; the walker's own `ok` always stands. `result_id` is the result's id when the walker mints it (a v4 or v7 UUID — a handset with no signal queues the checkpoint's photo against it): the same id again is this result, an id another result holds is refused as a duplicate, and a checkpoint recorded already under another id is refused naming it. `anomalies` is derived — the items answered not ok — and the round's totals are re-folded from its results. The result is linked to the checkpoint's room or asset and to the staff member behind the session. One write per checkpoint: recording it again replaces the result in place while the round is open, and an identical repeat writes nothing (even after the round has closed). `raise_fault` raises a work order through `create_work_order`'s own path — in the public area `raise_fault.area_id` names (never with a room_id), else against `raise_fault.room_id`, else the checkpoint's room, else the room its asset stands in, and for the checkpoint's asset — linked to the round (`work_order_from_round`) and the checkpoint (`work_order_from_checkpoint`) and counted on both; a fault with the title of one already raised from this checkpoint is that fault, not another. Photos attach to the result (`host_kind = checkpoint_result`). Emits `inspection_round.checkpoint_recorded`.\n\nEffects: create hospitality.checkpoint_result; modify hospitality.checkpoint_result; modify hospitality.inspection_round; link hospitality.link.checkpoint_result_in_round; link hospitality.link.checkpoint_result_for_room; link hospitality.link.checkpoint_result_for_asset; link hospitality.link.checkpoint_result_recorded_by; unlink hospitality.link.checkpoint_result_recorded_by; link hospitality.link.work_order_from_round; link hospitality.link.work_order_from_checkpoint; create hospitality.work_order; link hospitality.link.work_order_from_triage; link hospitality.link.work_order_for_room; link hospitality.link.work_order_assigned_to; create hospitality.room_status_block; link hospitality.link.room_status_block_for_room; link hospitality.link.work_order_holds_block; modify hospitality.availability_day; link hospitality.link.work_order_for_asset; link hospitality.link.work_order_reported_by_stay; link hospitality.link.work_order_of_fault_type; link hospitality.link.work_order_for_area.", "operationId": "apply_hospitality_action_record_checkpoint", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "completed_at": { "format": "date-time", "title": "When the checkpoint was finished (defaults to now)", "type": "string" }, "items": { "items": { "properties": { "code": { "type": "string" }, "ok": { "type": "boolean" }, "text": { "type": "string" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "code" ], "type": "object" }, "title": "Checkpoint answers", "type": "array" }, "observations": { "title": "What the walker noticed at the checkpoint", "type": "string" }, "position": { "title": "The checkpoint's position in the round", "type": "integer" }, "raise_fault": { "properties": { "area_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.public_area" }, "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "type": "string" }, "description": { "type": "string" }, "room_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.room" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "type": "string" }, "title": { "type": "string" } }, "required": [ "title", "category", "severity" ], "title": "Checkpoint fault", "type": "object" }, "result_id": { "title": "The result's id, minted by the walker (a v4 or v7 UUID)", "type": "string" }, "started_at": { "format": "date-time", "title": "When the walker began the checkpoint", "type": "string" } }, "required": [ "position", "items" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.inspection_round" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.checkpoint_result_in_round", "hospitality.link.checkpoint_result_for_room", "hospitality.link.checkpoint_result_for_asset", "hospitality.link.checkpoint_result_recorded_by", "hospitality.link.work_order_from_round", "hospitality.link.work_order_from_checkpoint", "hospitality.link.work_order_from_triage", "hospitality.link.work_order_for_room", "hospitality.link.work_order_assigned_to", "hospitality.link.room_status_block_for_room", "hospitality.link.work_order_holds_block", "hospitality.link.work_order_for_asset", "hospitality.link.work_order_reported_by_stay", "hospitality.link.work_order_of_fault_type", "hospitality.link.work_order_for_area" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.checkpoint_result", "hospitality.inspection_round", "hospitality.work_order", "hospitality.room_status_block", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_checkpoint:apply" ] } ], "summary": "Record checkpoint", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.record_checkpoint/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_checkpoint` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_checkpoint:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_checkpoint", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "completed_at": { "format": "date-time", "title": "When the checkpoint was finished (defaults to now)", "type": "string" }, "items": { "items": { "properties": { "code": { "type": "string" }, "ok": { "type": "boolean" }, "text": { "type": "string" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "code" ], "type": "object" }, "title": "Checkpoint answers", "type": "array" }, "observations": { "title": "What the walker noticed at the checkpoint", "type": "string" }, "position": { "title": "The checkpoint's position in the round", "type": "integer" }, "raise_fault": { "properties": { "area_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.public_area" }, "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "type": "string" }, "description": { "type": "string" }, "room_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.room" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "type": "string" }, "title": { "type": "string" } }, "required": [ "title", "category", "severity" ], "title": "Checkpoint fault", "type": "object" }, "result_id": { "title": "The result's id, minted by the walker (a v4 or v7 UUID)", "type": "string" }, "started_at": { "format": "date-time", "title": "When the walker began the checkpoint", "type": "string" } }, "required": [ "position", "items" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.inspection_round" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.checkpoint_result_in_round", "hospitality.link.checkpoint_result_for_room", "hospitality.link.checkpoint_result_for_asset", "hospitality.link.checkpoint_result_recorded_by", "hospitality.link.work_order_from_round", "hospitality.link.work_order_from_checkpoint", "hospitality.link.work_order_from_triage", "hospitality.link.work_order_for_room", "hospitality.link.work_order_assigned_to", "hospitality.link.room_status_block_for_room", "hospitality.link.work_order_holds_block", "hospitality.link.work_order_for_asset", "hospitality.link.work_order_reported_by_stay", "hospitality.link.work_order_of_fault_type", "hospitality.link.work_order_for_area" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.checkpoint_result", "hospitality.inspection_round", "hospitality.work_order", "hospitality.room_status_block", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record checkpoint (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.record_checkpoint/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_checkpoint`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_checkpoint", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "completed_at": { "format": "date-time", "title": "When the checkpoint was finished (defaults to now)", "type": "string" }, "items": { "items": { "properties": { "code": { "type": "string" }, "ok": { "type": "boolean" }, "text": { "type": "string" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "code" ], "type": "object" }, "title": "Checkpoint answers", "type": "array" }, "observations": { "title": "What the walker noticed at the checkpoint", "type": "string" }, "position": { "title": "The checkpoint's position in the round", "type": "integer" }, "raise_fault": { "properties": { "area_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.public_area" }, "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "type": "string" }, "description": { "type": "string" }, "room_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.room" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "type": "string" }, "title": { "type": "string" } }, "required": [ "title", "category", "severity" ], "title": "Checkpoint fault", "type": "object" }, "result_id": { "title": "The result's id, minted by the walker (a v4 or v7 UUID)", "type": "string" }, "started_at": { "format": "date-time", "title": "When the walker began the checkpoint", "type": "string" } }, "required": [ "position", "items" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.inspection_round" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record checkpoint (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.record_checkpoint/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_checkpoint` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_checkpoint:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_checkpoint", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "completed_at": { "format": "date-time", "title": "When the checkpoint was finished (defaults to now)", "type": "string" }, "items": { "items": { "properties": { "code": { "type": "string" }, "ok": { "type": "boolean" }, "text": { "type": "string" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "code" ], "type": "object" }, "title": "Checkpoint answers", "type": "array" }, "observations": { "title": "What the walker noticed at the checkpoint", "type": "string" }, "position": { "title": "The checkpoint's position in the round", "type": "integer" }, "raise_fault": { "properties": { "area_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.public_area" }, "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "type": "string" }, "description": { "type": "string" }, "room_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.room" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "type": "string" }, "title": { "type": "string" } }, "required": [ "title", "category", "severity" ], "title": "Checkpoint fault", "type": "object" }, "result_id": { "title": "The result's id, minted by the walker (a v4 or v7 UUID)", "type": "string" }, "started_at": { "format": "date-time", "title": "When the walker began the checkpoint", "type": "string" } }, "required": [ "position", "items" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.inspection_round" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record checkpoint (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.record_companion_relationship/apply": { "post": { "description": "Record a typed companion relationship between two persons. Stored once with symmetric semantics — UI and queries read either direction. Idempotent on the unordered pair.\n\nEffects: link hospitality.link.person_companion_of; modify link hospitality.link.person_companion_of.", "operationId": "apply_hospitality_action_record_companion_relationship", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "companion_id": { "format": "uuid", "title": "Companion", "type": "string", "x-aerandil-references": "hospitality.person" }, "consent_to_share_recognition": { "title": "Companion consent to share recognition", "type": "boolean" }, "person_id": { "format": "uuid", "title": "Person", "type": "string", "x-aerandil-references": "hospitality.person" }, "relationship_kind": { "enum": [ "spouse", "partner", "family_member", "child", "parent", "sibling", "colleague", "friend", "assistant", "other" ], "title": "Relationship kind", "type": "string" } }, "required": [ "person_id", "companion_id", "relationship_kind", "consent_to_share_recognition" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "properties_updated" ] }, "link_type": { "enum": [ "hospitality.link.person_companion_of" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_companion_relationship:apply" ] } ], "summary": "Record companion relationship", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.record_companion_relationship/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_companion_relationship` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_companion_relationship:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_companion_relationship", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "companion_id": { "format": "uuid", "title": "Companion", "type": "string", "x-aerandil-references": "hospitality.person" }, "consent_to_share_recognition": { "title": "Companion consent to share recognition", "type": "boolean" }, "person_id": { "format": "uuid", "title": "Person", "type": "string", "x-aerandil-references": "hospitality.person" }, "relationship_kind": { "enum": [ "spouse", "partner", "family_member", "child", "parent", "sibling", "colleague", "friend", "assistant", "other" ], "title": "Relationship kind", "type": "string" } }, "required": [ "person_id", "companion_id", "relationship_kind", "consent_to_share_recognition" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "properties_updated" ] }, "link_type": { "enum": [ "hospitality.link.person_companion_of" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record companion relationship (dry-run)", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.record_companion_relationship/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_companion_relationship`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_companion_relationship", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "companion_id": { "format": "uuid", "title": "Companion", "type": "string", "x-aerandil-references": "hospitality.person" }, "consent_to_share_recognition": { "title": "Companion consent to share recognition", "type": "boolean" }, "person_id": { "format": "uuid", "title": "Person", "type": "string", "x-aerandil-references": "hospitality.person" }, "relationship_kind": { "enum": [ "spouse", "partner", "family_member", "child", "parent", "sibling", "colleague", "friend", "assistant", "other" ], "title": "Relationship kind", "type": "string" } }, "required": [ "person_id", "companion_id", "relationship_kind", "consent_to_share_recognition" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record companion relationship (dry-run)", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.record_companion_relationship/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_companion_relationship` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_companion_relationship:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_companion_relationship", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "companion_id": { "format": "uuid", "title": "Companion", "type": "string", "x-aerandil-references": "hospitality.person" }, "consent_to_share_recognition": { "title": "Companion consent to share recognition", "type": "boolean" }, "person_id": { "format": "uuid", "title": "Person", "type": "string", "x-aerandil-references": "hospitality.person" }, "relationship_kind": { "enum": [ "spouse", "partner", "family_member", "child", "parent", "sibling", "colleague", "friend", "assistant", "other" ], "title": "Relationship kind", "type": "string" } }, "required": [ "person_id", "companion_id", "relationship_kind", "consent_to_share_recognition" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record companion relationship (rollup delta)", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.record_compensation_result/apply": { "post": { "description": "Records the outcome of a declared compensating action / function / manual step against the original successful terminal step. When `compensation_step_run_id` is set the handler creates the `workflow_step_run_compensates_step_run` self-link from the compensating row to the original. Recomputes the parent run's compensation state and emits `workflow_step.compensated` / `workflow_step.compensation_failed`. Failed compensation is terminal evidence, never an excuse to delete the original step.\n\nEffects: modify hospitality.workflow_step_run; modify hospitality.workflow_run; link hospitality.link.workflow_step_run_compensates_step_run.", "operationId": "apply_hospitality_action_record_compensation_result", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "compensation_note": { "title": "Bounded text note", "type": "string" }, "compensation_status": { "enum": [ "compensated", "compensation_failed", "manual_required" ], "title": "compensated | compensation_failed | manual_required", "type": "string" }, "compensation_step_run_id": { "title": "Creates `workflow_step_run_compensates_step_run` when set", "type": "string" }, "external_reference": { "title": "PSP/PMS/manual-task reference", "type": "string" } }, "required": [ "compensation_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_step_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.workflow_step_run_compensates_step_run" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.workflow_step_run", "hospitality.workflow_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_compensation_result:apply" ] } ], "summary": "Record compensation result", "tags": [ "workflows" ] } }, "/v1/actions/hospitality.action.record_compensation_result/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_compensation_result` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_compensation_result:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_compensation_result", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "compensation_note": { "title": "Bounded text note", "type": "string" }, "compensation_status": { "enum": [ "compensated", "compensation_failed", "manual_required" ], "title": "compensated | compensation_failed | manual_required", "type": "string" }, "compensation_step_run_id": { "title": "Creates `workflow_step_run_compensates_step_run` when set", "type": "string" }, "external_reference": { "title": "PSP/PMS/manual-task reference", "type": "string" } }, "required": [ "compensation_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_step_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.workflow_step_run_compensates_step_run" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.workflow_step_run", "hospitality.workflow_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record compensation result (dry-run)", "tags": [ "workflows" ] } }, "/v1/actions/hospitality.action.record_compensation_result/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_compensation_result`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_compensation_result", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "compensation_note": { "title": "Bounded text note", "type": "string" }, "compensation_status": { "enum": [ "compensated", "compensation_failed", "manual_required" ], "title": "compensated | compensation_failed | manual_required", "type": "string" }, "compensation_step_run_id": { "title": "Creates `workflow_step_run_compensates_step_run` when set", "type": "string" }, "external_reference": { "title": "PSP/PMS/manual-task reference", "type": "string" } }, "required": [ "compensation_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_step_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record compensation result (dry-run)", "tags": [ "workflows" ] } }, "/v1/actions/hospitality.action.record_compensation_result/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_compensation_result` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_compensation_result:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_compensation_result", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "compensation_note": { "title": "Bounded text note", "type": "string" }, "compensation_status": { "enum": [ "compensated", "compensation_failed", "manual_required" ], "title": "compensated | compensation_failed | manual_required", "type": "string" }, "compensation_step_run_id": { "title": "Creates `workflow_step_run_compensates_step_run` when set", "type": "string" }, "external_reference": { "title": "PSP/PMS/manual-task reference", "type": "string" } }, "required": [ "compensation_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_step_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record compensation result (rollup delta)", "tags": [ "workflows" ] } }, "/v1/actions/hospitality.action.record_demand_forecast/apply": { "post": { "description": "Record a forecast for a property: one point per arrival night, all as of one instant, for one segment, from one source. `points` is a JSON array of `{arrival_date, forecast_rooms, forecast_adr, demand_rooms?, on_the_books?, external_ref?}` — ADR in the property's default currency, `demand_rooms` the unconstrained estimate when the forecaster has one. Every point becomes an immutable `demand_forecast` and emits the `forecast.point.recorded` feed event the rate-recommendation path emits, so the realization sweep grades it against the night's actual. A point carrying an `external_ref` already recorded is skipped, object and feed event both: a replayed re-forecast writes nothing.\n\nEffects: create hospitality.demand_forecast; link hospitality.link.demand_forecast_for_property.", "operationId": "apply_hospitality_action_record_demand_forecast", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "forecast_as_of": { "format": "date-time", "title": "When the forecast was made (defaults to now; must not be in the future)", "type": "string" }, "notes": { "title": "How the forecast was made", "type": "string" }, "points": { "title": "JSON array of points: {arrival_date, forecast_rooms, forecast_adr, demand_rooms?, on_the_books?, external_ref?}" }, "property_id": { "format": "uuid", "title": "The house the forecast is for", "type": "string", "x-aerandil-references": "hospitality.property" }, "segment": { "enum": [ "total", "transient", "group", "contract" ], "title": "Market segment forecast, or `total` for the house as a whole", "type": "string" }, "source": { "enum": [ "desk", "rms", "import" ], "title": "Who produced the forecast", "type": "string" } }, "required": [ "property_id", "segment", "source", "points" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.demand_forecast_for_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.demand_forecast" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_demand_forecast:apply" ] } ], "summary": "Record demand forecast", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.record_demand_forecast/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_demand_forecast` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_demand_forecast:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_demand_forecast", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "forecast_as_of": { "format": "date-time", "title": "When the forecast was made (defaults to now; must not be in the future)", "type": "string" }, "notes": { "title": "How the forecast was made", "type": "string" }, "points": { "title": "JSON array of points: {arrival_date, forecast_rooms, forecast_adr, demand_rooms?, on_the_books?, external_ref?}" }, "property_id": { "format": "uuid", "title": "The house the forecast is for", "type": "string", "x-aerandil-references": "hospitality.property" }, "segment": { "enum": [ "total", "transient", "group", "contract" ], "title": "Market segment forecast, or `total` for the house as a whole", "type": "string" }, "source": { "enum": [ "desk", "rms", "import" ], "title": "Who produced the forecast", "type": "string" } }, "required": [ "property_id", "segment", "source", "points" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.demand_forecast_for_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.demand_forecast" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record demand forecast (dry-run)", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.record_demand_forecast/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_demand_forecast`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_demand_forecast", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "forecast_as_of": { "format": "date-time", "title": "When the forecast was made (defaults to now; must not be in the future)", "type": "string" }, "notes": { "title": "How the forecast was made", "type": "string" }, "points": { "title": "JSON array of points: {arrival_date, forecast_rooms, forecast_adr, demand_rooms?, on_the_books?, external_ref?}" }, "property_id": { "format": "uuid", "title": "The house the forecast is for", "type": "string", "x-aerandil-references": "hospitality.property" }, "segment": { "enum": [ "total", "transient", "group", "contract" ], "title": "Market segment forecast, or `total` for the house as a whole", "type": "string" }, "source": { "enum": [ "desk", "rms", "import" ], "title": "Who produced the forecast", "type": "string" } }, "required": [ "property_id", "segment", "source", "points" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record demand forecast (dry-run)", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.record_demand_forecast/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_demand_forecast` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_demand_forecast:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_demand_forecast", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "forecast_as_of": { "format": "date-time", "title": "When the forecast was made (defaults to now; must not be in the future)", "type": "string" }, "notes": { "title": "How the forecast was made", "type": "string" }, "points": { "title": "JSON array of points: {arrival_date, forecast_rooms, forecast_adr, demand_rooms?, on_the_books?, external_ref?}" }, "property_id": { "format": "uuid", "title": "The house the forecast is for", "type": "string", "x-aerandil-references": "hospitality.property" }, "segment": { "enum": [ "total", "transient", "group", "contract" ], "title": "Market segment forecast, or `total` for the house as a whole", "type": "string" }, "source": { "enum": [ "desk", "rms", "import" ], "title": "Who produced the forecast", "type": "string" } }, "required": [ "property_id", "segment", "source", "points" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record demand forecast (rollup delta)", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.record_deposit_payment/apply": { "post": { "description": "Record a deposit taken before arrival. The money lands on the booking's own account — opened here if this is the first — as an ordinary settled payment, and `deposit_paid_amount` / `prepayment_status` advance on the reservation. At check-in `apply_deposit_to_folio` moves it onto the stay's folio; until then the account is where it is, which is what makes it visible, billable and refundable. Pass `psp_reference` for a deposit taken on a card: without the processor's own reference the payment can be found but not returned, and a refund becomes a ledger gesture instead of money moving.\n\nEffects: modify hospitality.reservation; create hospitality.payment; create hospitality.folio; link hospitality.link.reservation_has_folio; link hospitality.link.folio_has_payment; link hospitality.link.payment_for_reservation; modify hospitality.folio.", "operationId": "apply_hospitality_action_record_deposit_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "method": { "enum": [ "cash", "credit_card", "debit_card", "bank_transfer", "voucher", "loyalty_points", "direct_billing", "mobile_wallet", "ota_collected", "other" ], "title": "Payment method", "type": "string" }, "payment_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment amount", "type": "object" }, "psp_reference": { "title": "The processor's reference for the charge — the handle a refund acts on, and the only thing that survives into a dispute", "type": "string" }, "received_at": { "format": "date-time", "title": "Received at", "type": "string" } }, "required": [ "payment_amount", "received_at", "method" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.reservation_has_folio", "hospitality.link.folio_has_payment", "hospitality.link.payment_for_reservation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.reservation", "hospitality.payment", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_deposit_payment:apply" ] } ], "summary": "Record deposit payment", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.record_deposit_payment/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_deposit_payment` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_deposit_payment:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_deposit_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "method": { "enum": [ "cash", "credit_card", "debit_card", "bank_transfer", "voucher", "loyalty_points", "direct_billing", "mobile_wallet", "ota_collected", "other" ], "title": "Payment method", "type": "string" }, "payment_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment amount", "type": "object" }, "psp_reference": { "title": "The processor's reference for the charge — the handle a refund acts on, and the only thing that survives into a dispute", "type": "string" }, "received_at": { "format": "date-time", "title": "Received at", "type": "string" } }, "required": [ "payment_amount", "received_at", "method" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.reservation_has_folio", "hospitality.link.folio_has_payment", "hospitality.link.payment_for_reservation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.reservation", "hospitality.payment", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record deposit payment (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.record_deposit_payment/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_deposit_payment`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_deposit_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "method": { "enum": [ "cash", "credit_card", "debit_card", "bank_transfer", "voucher", "loyalty_points", "direct_billing", "mobile_wallet", "ota_collected", "other" ], "title": "Payment method", "type": "string" }, "payment_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment amount", "type": "object" }, "psp_reference": { "title": "The processor's reference for the charge — the handle a refund acts on, and the only thing that survives into a dispute", "type": "string" }, "received_at": { "format": "date-time", "title": "Received at", "type": "string" } }, "required": [ "payment_amount", "received_at", "method" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record deposit payment (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.record_deposit_payment/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_deposit_payment` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_deposit_payment:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_deposit_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "method": { "enum": [ "cash", "credit_card", "debit_card", "bank_transfer", "voucher", "loyalty_points", "direct_billing", "mobile_wallet", "ota_collected", "other" ], "title": "Payment method", "type": "string" }, "payment_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment amount", "type": "object" }, "psp_reference": { "title": "The processor's reference for the charge — the handle a refund acts on, and the only thing that survives into a dispute", "type": "string" }, "received_at": { "format": "date-time", "title": "Received at", "type": "string" } }, "required": [ "payment_amount", "received_at", "method" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record deposit payment (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.record_external_payment/apply": { "post": { "description": "Record a vendor-sourced payment against the folio of a reservation's stay (window 1 unless `window_number` says otherwise) — the settle leg of post_external_charge; a payment taken before the booking has a stay (a deposit) lands on the booking's own account, opened on first use. Business time via `received_at`, replay-safe via `external_ref` (the payment business key), and accepts a closed folio for the same vendor-mirror reason. Settles immediately; refunds stay with refund_payment.\n\nEffects: create hospitality.payment; link hospitality.link.folio_has_payment; modify hospitality.folio; create hospitality.folio; link hospitality.link.reservation_has_folio.", "operationId": "apply_hospitality_action_record_external_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "external_ref": { "title": "Source-system key (makes the record replay-safe)", "type": "string" }, "method": { "enum": [ "cash", "credit_card", "debit_card", "bank_transfer", "voucher", "loyalty_points", "direct_billing", "mobile_wallet", "ota_collected", "other" ], "title": "Method", "type": "string" }, "received_at": { "format": "date-time", "title": "Receipt instant in the source system (defaults to now)", "type": "string" }, "reference": { "title": "Reference", "type": "string" }, "reservation_id": { "format": "uuid", "title": "Reservation whose stay folio receives the payment", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "reservation_room_id": { "format": "uuid", "title": "Leg whose stay folio receives the payment (required when the reservation has more than one stay)", "type": "string", "x-aerandil-references": "hospitality.reservation_room" }, "window_number": { "title": "Folio window (defaults to 1)", "type": "integer" } }, "required": [ "reservation_id", "amount", "method" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_payment", "hospitality.link.reservation_has_folio" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.payment", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_external_payment:apply" ] } ], "summary": "Record external payment", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.record_external_payment/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_external_payment` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_external_payment:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_external_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "external_ref": { "title": "Source-system key (makes the record replay-safe)", "type": "string" }, "method": { "enum": [ "cash", "credit_card", "debit_card", "bank_transfer", "voucher", "loyalty_points", "direct_billing", "mobile_wallet", "ota_collected", "other" ], "title": "Method", "type": "string" }, "received_at": { "format": "date-time", "title": "Receipt instant in the source system (defaults to now)", "type": "string" }, "reference": { "title": "Reference", "type": "string" }, "reservation_id": { "format": "uuid", "title": "Reservation whose stay folio receives the payment", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "reservation_room_id": { "format": "uuid", "title": "Leg whose stay folio receives the payment (required when the reservation has more than one stay)", "type": "string", "x-aerandil-references": "hospitality.reservation_room" }, "window_number": { "title": "Folio window (defaults to 1)", "type": "integer" } }, "required": [ "reservation_id", "amount", "method" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_payment", "hospitality.link.reservation_has_folio" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.payment", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record external payment (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.record_external_payment/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_external_payment`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_external_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "external_ref": { "title": "Source-system key (makes the record replay-safe)", "type": "string" }, "method": { "enum": [ "cash", "credit_card", "debit_card", "bank_transfer", "voucher", "loyalty_points", "direct_billing", "mobile_wallet", "ota_collected", "other" ], "title": "Method", "type": "string" }, "received_at": { "format": "date-time", "title": "Receipt instant in the source system (defaults to now)", "type": "string" }, "reference": { "title": "Reference", "type": "string" }, "reservation_id": { "format": "uuid", "title": "Reservation whose stay folio receives the payment", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "reservation_room_id": { "format": "uuid", "title": "Leg whose stay folio receives the payment (required when the reservation has more than one stay)", "type": "string", "x-aerandil-references": "hospitality.reservation_room" }, "window_number": { "title": "Folio window (defaults to 1)", "type": "integer" } }, "required": [ "reservation_id", "amount", "method" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record external payment (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.record_external_payment/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_external_payment` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_external_payment:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_external_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "external_ref": { "title": "Source-system key (makes the record replay-safe)", "type": "string" }, "method": { "enum": [ "cash", "credit_card", "debit_card", "bank_transfer", "voucher", "loyalty_points", "direct_billing", "mobile_wallet", "ota_collected", "other" ], "title": "Method", "type": "string" }, "received_at": { "format": "date-time", "title": "Receipt instant in the source system (defaults to now)", "type": "string" }, "reference": { "title": "Reference", "type": "string" }, "reservation_id": { "format": "uuid", "title": "Reservation whose stay folio receives the payment", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "reservation_room_id": { "format": "uuid", "title": "Leg whose stay folio receives the payment (required when the reservation has more than one stay)", "type": "string", "x-aerandil-references": "hospitality.reservation_room" }, "window_number": { "title": "Folio window (defaults to 1)", "type": "integer" } }, "required": [ "reservation_id", "amount", "method" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record external payment (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.record_external_refund/apply": { "post": { "description": "Mirror a vendor-sourced refund as a pending negative-amount Payment leg against the original settled payment it returns money from — the refund twin of record_external_payment. Replay-safe via `external_ref` (the payment business key): a second call with the same key is a no-op. Validators reject: target not settled, target already a refund leg, target on no folio or a void folio, zero amount, currency mismatch, and a leg that would take the refunded total past the original. A closed folio is accepted (the vendor's bill may already be sealed). The amount is taken as a magnitude, since vendors disagree on the sign of a refund. The dispute block and the one-pending-leg rule stay with refund_payment: they guard a refund being sent, and this one already was. The outcome lands via resolve_payment_refund.\n\nEffects: create hospitality.payment; link hospitality.link.folio_has_payment; link hospitality.link.payment_refunds_payment.", "operationId": "apply_hospitality_action_record_external_refund", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "external_ref": { "title": "Source-system key (makes the record replay-safe)", "type": "string" }, "psp_refund_reference": { "title": "The vendor's processor reference for the refund, when it has one", "type": "string" }, "refund_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Refund amount (magnitude; either sign accepted)", "type": "object" }, "refund_note": { "title": "The vendor's free-text reason, max 1024 chars", "type": "string" }, "refund_reason": { "enum": [ "duplicate", "fraudulent", "requested_by_customer", "reservation_cancelled", "deposit_return", "service_recovery", "overcharge_correction", "no_show_policy_exception", "package_component_refund", "membership_cancellation", "chargeback_prevention", "other" ], "title": "Closed REFUND_REASONS taxonomy (defaults to `other` — vendors send free text, which lands in refund_note)", "type": "string" }, "refund_requested_at": { "format": "date-time", "title": "Refund instant in the source system (defaults to now)", "type": "string" } }, "required": [ "external_ref", "refund_amount" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_payment", "hospitality.link.payment_refunds_payment" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.payment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_external_refund:apply" ] } ], "summary": "Record external refund", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.record_external_refund/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_external_refund` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_external_refund:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_external_refund", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "external_ref": { "title": "Source-system key (makes the record replay-safe)", "type": "string" }, "psp_refund_reference": { "title": "The vendor's processor reference for the refund, when it has one", "type": "string" }, "refund_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Refund amount (magnitude; either sign accepted)", "type": "object" }, "refund_note": { "title": "The vendor's free-text reason, max 1024 chars", "type": "string" }, "refund_reason": { "enum": [ "duplicate", "fraudulent", "requested_by_customer", "reservation_cancelled", "deposit_return", "service_recovery", "overcharge_correction", "no_show_policy_exception", "package_component_refund", "membership_cancellation", "chargeback_prevention", "other" ], "title": "Closed REFUND_REASONS taxonomy (defaults to `other` — vendors send free text, which lands in refund_note)", "type": "string" }, "refund_requested_at": { "format": "date-time", "title": "Refund instant in the source system (defaults to now)", "type": "string" } }, "required": [ "external_ref", "refund_amount" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_payment", "hospitality.link.payment_refunds_payment" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.payment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record external refund (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.record_external_refund/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_external_refund`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_external_refund", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "external_ref": { "title": "Source-system key (makes the record replay-safe)", "type": "string" }, "psp_refund_reference": { "title": "The vendor's processor reference for the refund, when it has one", "type": "string" }, "refund_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Refund amount (magnitude; either sign accepted)", "type": "object" }, "refund_note": { "title": "The vendor's free-text reason, max 1024 chars", "type": "string" }, "refund_reason": { "enum": [ "duplicate", "fraudulent", "requested_by_customer", "reservation_cancelled", "deposit_return", "service_recovery", "overcharge_correction", "no_show_policy_exception", "package_component_refund", "membership_cancellation", "chargeback_prevention", "other" ], "title": "Closed REFUND_REASONS taxonomy (defaults to `other` — vendors send free text, which lands in refund_note)", "type": "string" }, "refund_requested_at": { "format": "date-time", "title": "Refund instant in the source system (defaults to now)", "type": "string" } }, "required": [ "external_ref", "refund_amount" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record external refund (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.record_external_refund/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_external_refund` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_external_refund:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_external_refund", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "external_ref": { "title": "Source-system key (makes the record replay-safe)", "type": "string" }, "psp_refund_reference": { "title": "The vendor's processor reference for the refund, when it has one", "type": "string" }, "refund_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Refund amount (magnitude; either sign accepted)", "type": "object" }, "refund_note": { "title": "The vendor's free-text reason, max 1024 chars", "type": "string" }, "refund_reason": { "enum": [ "duplicate", "fraudulent", "requested_by_customer", "reservation_cancelled", "deposit_return", "service_recovery", "overcharge_correction", "no_show_policy_exception", "package_component_refund", "membership_cancellation", "chargeback_prevention", "other" ], "title": "Closed REFUND_REASONS taxonomy (defaults to `other` — vendors send free text, which lands in refund_note)", "type": "string" }, "refund_requested_at": { "format": "date-time", "title": "Refund instant in the source system (defaults to now)", "type": "string" } }, "required": [ "external_ref", "refund_amount" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record external refund (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.record_federated_aggregation_result/apply": { "post": { "description": "Finalize aggregation after enough contributions are accepted. Verifies accepted contribution counts and thresholds, commits or releases privacy budget, sets run status to `output_review`, `completed`, `failed`, or `quarantined`, and creates a draft `federated_output` when aggregation succeeded. Validators (commit 5): `run_aggregation_requires_threshold_satisfaction`, `run_aggregation_max_contributor_share_satisfied`.\n\nEffects: modify hospitality.federated_run; create hospitality.federated_output; link hospitality.link.federated_output_from_run; create hospitality.privacy_budget_event; modify hospitality.privacy_budget_account.", "operationId": "apply_hospitality_action_record_federated_aggregation_result", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "aggregate_payload_hash": { "title": "Required when aggregate_payload_reference is set", "type": "string" }, "aggregate_payload_reference": { "title": "Aggregate payload reference (opaque)", "type": "string" }, "aggregation_status": { "enum": [ "succeeded", "failed", "quarantined" ], "title": "succeeded | failed | quarantined", "type": "string" }, "draft_output_kind": { "enum": [ "benchmark_report", "calibration_curve", "aggregate_metric", "model_artifact", "signal_package", "governance_card" ], "title": "Output kind for the draft output created on success", "type": "string" }, "draft_output_schema_version": { "title": "Output schema version for the draft output", "type": "string" }, "failure_reason": { "title": "Bounded; required for failed / quarantined", "type": "string" }, "participants_accepted": { "title": "Accepted participant count", "type": "integer" }, "participants_suppressed": { "title": "Suppressed participant count", "type": "integer" }, "privacy_budget_spend": { "title": "Actual budget spend (JSON)" }, "suppression_reasons": { "items": { "enum": [ "minimum_tenants_not_met", "minimum_properties_not_met", "minimum_subjects_not_met", "max_contributor_share_exceeded", "privacy_budget_exhausted", "high_variance", "data_quality_mismatch", "legal_basis_missing", "participant_withdrawal", "reviewer_blocked", "security_incident" ], "type": "string" }, "title": "Reasons for suppression", "type": "array" } }, "required": [ "aggregation_status", "participants_accepted", "participants_suppressed", "privacy_budget_spend" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.federated_output_from_run" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.federated_run", "hospitality.federated_output", "hospitality.privacy_budget_event", "hospitality.privacy_budget_account" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_federated_aggregation_result:apply" ] } ], "summary": "Record federated aggregation result", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.record_federated_aggregation_result/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_federated_aggregation_result` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_federated_aggregation_result:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_federated_aggregation_result", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "aggregate_payload_hash": { "title": "Required when aggregate_payload_reference is set", "type": "string" }, "aggregate_payload_reference": { "title": "Aggregate payload reference (opaque)", "type": "string" }, "aggregation_status": { "enum": [ "succeeded", "failed", "quarantined" ], "title": "succeeded | failed | quarantined", "type": "string" }, "draft_output_kind": { "enum": [ "benchmark_report", "calibration_curve", "aggregate_metric", "model_artifact", "signal_package", "governance_card" ], "title": "Output kind for the draft output created on success", "type": "string" }, "draft_output_schema_version": { "title": "Output schema version for the draft output", "type": "string" }, "failure_reason": { "title": "Bounded; required for failed / quarantined", "type": "string" }, "participants_accepted": { "title": "Accepted participant count", "type": "integer" }, "participants_suppressed": { "title": "Suppressed participant count", "type": "integer" }, "privacy_budget_spend": { "title": "Actual budget spend (JSON)" }, "suppression_reasons": { "items": { "enum": [ "minimum_tenants_not_met", "minimum_properties_not_met", "minimum_subjects_not_met", "max_contributor_share_exceeded", "privacy_budget_exhausted", "high_variance", "data_quality_mismatch", "legal_basis_missing", "participant_withdrawal", "reviewer_blocked", "security_incident" ], "type": "string" }, "title": "Reasons for suppression", "type": "array" } }, "required": [ "aggregation_status", "participants_accepted", "participants_suppressed", "privacy_budget_spend" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.federated_output_from_run" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.federated_run", "hospitality.federated_output", "hospitality.privacy_budget_event", "hospitality.privacy_budget_account" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record federated aggregation result (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.record_federated_aggregation_result/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_federated_aggregation_result`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_federated_aggregation_result", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "aggregate_payload_hash": { "title": "Required when aggregate_payload_reference is set", "type": "string" }, "aggregate_payload_reference": { "title": "Aggregate payload reference (opaque)", "type": "string" }, "aggregation_status": { "enum": [ "succeeded", "failed", "quarantined" ], "title": "succeeded | failed | quarantined", "type": "string" }, "draft_output_kind": { "enum": [ "benchmark_report", "calibration_curve", "aggregate_metric", "model_artifact", "signal_package", "governance_card" ], "title": "Output kind for the draft output created on success", "type": "string" }, "draft_output_schema_version": { "title": "Output schema version for the draft output", "type": "string" }, "failure_reason": { "title": "Bounded; required for failed / quarantined", "type": "string" }, "participants_accepted": { "title": "Accepted participant count", "type": "integer" }, "participants_suppressed": { "title": "Suppressed participant count", "type": "integer" }, "privacy_budget_spend": { "title": "Actual budget spend (JSON)" }, "suppression_reasons": { "items": { "enum": [ "minimum_tenants_not_met", "minimum_properties_not_met", "minimum_subjects_not_met", "max_contributor_share_exceeded", "privacy_budget_exhausted", "high_variance", "data_quality_mismatch", "legal_basis_missing", "participant_withdrawal", "reviewer_blocked", "security_incident" ], "type": "string" }, "title": "Reasons for suppression", "type": "array" } }, "required": [ "aggregation_status", "participants_accepted", "participants_suppressed", "privacy_budget_spend" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record federated aggregation result (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.record_federated_aggregation_result/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_federated_aggregation_result` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_federated_aggregation_result:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_federated_aggregation_result", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "aggregate_payload_hash": { "title": "Required when aggregate_payload_reference is set", "type": "string" }, "aggregate_payload_reference": { "title": "Aggregate payload reference (opaque)", "type": "string" }, "aggregation_status": { "enum": [ "succeeded", "failed", "quarantined" ], "title": "succeeded | failed | quarantined", "type": "string" }, "draft_output_kind": { "enum": [ "benchmark_report", "calibration_curve", "aggregate_metric", "model_artifact", "signal_package", "governance_card" ], "title": "Output kind for the draft output created on success", "type": "string" }, "draft_output_schema_version": { "title": "Output schema version for the draft output", "type": "string" }, "failure_reason": { "title": "Bounded; required for failed / quarantined", "type": "string" }, "participants_accepted": { "title": "Accepted participant count", "type": "integer" }, "participants_suppressed": { "title": "Suppressed participant count", "type": "integer" }, "privacy_budget_spend": { "title": "Actual budget spend (JSON)" }, "suppression_reasons": { "items": { "enum": [ "minimum_tenants_not_met", "minimum_properties_not_met", "minimum_subjects_not_met", "max_contributor_share_exceeded", "privacy_budget_exhausted", "high_variance", "data_quality_mismatch", "legal_basis_missing", "participant_withdrawal", "reviewer_blocked", "security_incident" ], "type": "string" }, "title": "Reasons for suppression", "type": "array" } }, "required": [ "aggregation_status", "participants_accepted", "participants_suppressed", "privacy_budget_spend" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record federated aggregation result (rollup delta)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.record_federated_contribution/apply": { "post": { "description": "Record one participant contribution metadata and payload reference. Verifies run is collecting and participant eligible, validates code digest, window, payload bounds, and forbidden raw data, validates local privacy spend against reserved budget, and marks the contribution `accepted`, `rejected`, or `suppressed`. Idempotent on `run_id + participation_id + contribution_slot`. Validators (commit 5): `contribution_window_must_match_run`, `contribution_local_code_digest_must_match_definition`, `contribution_payload_size_must_be_bounded`, `contribution_clipping_required_for_model_update`, `contribution_no_raw_payload_inline`.\n\nEffects: create hospitality.federated_contribution; link hospitality.link.federated_contribution_for_run; link hospitality.link.federated_contribution_from_participation; modify hospitality.federated_run.", "operationId": "apply_hospitality_action_record_federated_contribution", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "attestation_reference": { "title": "TEE / runner attestation if used", "type": "string" }, "clipping_applied": { "title": "Required true for model updates", "type": "boolean" }, "contribution_kind": { "enum": [ "encrypted_aggregate", "noisy_aggregate", "model_update", "metrics_only", "attestation_only" ], "title": "Contribution kind", "type": "string" }, "contribution_slot": { "title": "Slot discriminator when definition declares multiple slots", "type": "string" }, "delta_spent": { "format": "decimal", "title": "Local DP spend", "type": "string" }, "epsilon_spent": { "format": "decimal", "title": "Local DP spend", "type": "string" }, "input_snapshot_hash": { "title": "Hash over local eligible input snapshot metadata", "type": "string" }, "input_window_end": { "format": "date-time", "title": "Must match run", "type": "string" }, "input_window_start": { "format": "date-time", "title": "Must match run", "type": "string" }, "local_code_digest": { "title": "Must match approved definition unless override recorded", "type": "string" }, "local_record_count_bucket": { "enum": [ "lt_10", "10_49", "50_99", "100_499", "500_999", "1000_plus" ], "title": "Bucketed record count", "type": "string" }, "local_runner_version": { "title": "Runner or agent version", "type": "string" }, "local_subject_count_bucket": { "enum": [ "lt_10", "10_49", "50_99", "100_499", "500_999", "1000_plus" ], "title": "Required for person-affecting definitions", "type": "string" }, "participation_id": { "title": "Participation id", "type": "string" }, "payload_hash": { "title": "Required when payload_reference is set", "type": "string" }, "payload_reference": { "title": "Encrypted payload / clean-room output / secure aggregation share ref", "type": "string" }, "payload_size_bytes": { "title": "Safety bound", "type": "integer" }, "rejection_reason": { "title": "Bounded; required for rejected / suppressed", "type": "string" }, "result_status": { "enum": [ "accepted", "rejected", "suppressed" ], "title": "accepted | rejected | suppressed", "type": "string" }, "secure_aggregation_mask_ref": { "title": "Optional protocol metadata", "type": "string" }, "validation_warnings": { "items": { "type": "string" }, "title": "Local runner warnings", "type": "array" } }, "required": [ "participation_id", "contribution_kind", "local_code_digest", "local_runner_version", "input_snapshot_hash", "input_window_start", "input_window_end", "local_record_count_bucket", "clipping_applied", "result_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.federated_contribution_for_run", "hospitality.link.federated_contribution_from_participation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.federated_contribution", "hospitality.federated_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_federated_contribution:apply" ] } ], "summary": "Record federated contribution", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.record_federated_contribution/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_federated_contribution` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_federated_contribution:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_federated_contribution", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "attestation_reference": { "title": "TEE / runner attestation if used", "type": "string" }, "clipping_applied": { "title": "Required true for model updates", "type": "boolean" }, "contribution_kind": { "enum": [ "encrypted_aggregate", "noisy_aggregate", "model_update", "metrics_only", "attestation_only" ], "title": "Contribution kind", "type": "string" }, "contribution_slot": { "title": "Slot discriminator when definition declares multiple slots", "type": "string" }, "delta_spent": { "format": "decimal", "title": "Local DP spend", "type": "string" }, "epsilon_spent": { "format": "decimal", "title": "Local DP spend", "type": "string" }, "input_snapshot_hash": { "title": "Hash over local eligible input snapshot metadata", "type": "string" }, "input_window_end": { "format": "date-time", "title": "Must match run", "type": "string" }, "input_window_start": { "format": "date-time", "title": "Must match run", "type": "string" }, "local_code_digest": { "title": "Must match approved definition unless override recorded", "type": "string" }, "local_record_count_bucket": { "enum": [ "lt_10", "10_49", "50_99", "100_499", "500_999", "1000_plus" ], "title": "Bucketed record count", "type": "string" }, "local_runner_version": { "title": "Runner or agent version", "type": "string" }, "local_subject_count_bucket": { "enum": [ "lt_10", "10_49", "50_99", "100_499", "500_999", "1000_plus" ], "title": "Required for person-affecting definitions", "type": "string" }, "participation_id": { "title": "Participation id", "type": "string" }, "payload_hash": { "title": "Required when payload_reference is set", "type": "string" }, "payload_reference": { "title": "Encrypted payload / clean-room output / secure aggregation share ref", "type": "string" }, "payload_size_bytes": { "title": "Safety bound", "type": "integer" }, "rejection_reason": { "title": "Bounded; required for rejected / suppressed", "type": "string" }, "result_status": { "enum": [ "accepted", "rejected", "suppressed" ], "title": "accepted | rejected | suppressed", "type": "string" }, "secure_aggregation_mask_ref": { "title": "Optional protocol metadata", "type": "string" }, "validation_warnings": { "items": { "type": "string" }, "title": "Local runner warnings", "type": "array" } }, "required": [ "participation_id", "contribution_kind", "local_code_digest", "local_runner_version", "input_snapshot_hash", "input_window_start", "input_window_end", "local_record_count_bucket", "clipping_applied", "result_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.federated_contribution_for_run", "hospitality.link.federated_contribution_from_participation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.federated_contribution", "hospitality.federated_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record federated contribution (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.record_federated_contribution/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_federated_contribution`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_federated_contribution", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "attestation_reference": { "title": "TEE / runner attestation if used", "type": "string" }, "clipping_applied": { "title": "Required true for model updates", "type": "boolean" }, "contribution_kind": { "enum": [ "encrypted_aggregate", "noisy_aggregate", "model_update", "metrics_only", "attestation_only" ], "title": "Contribution kind", "type": "string" }, "contribution_slot": { "title": "Slot discriminator when definition declares multiple slots", "type": "string" }, "delta_spent": { "format": "decimal", "title": "Local DP spend", "type": "string" }, "epsilon_spent": { "format": "decimal", "title": "Local DP spend", "type": "string" }, "input_snapshot_hash": { "title": "Hash over local eligible input snapshot metadata", "type": "string" }, "input_window_end": { "format": "date-time", "title": "Must match run", "type": "string" }, "input_window_start": { "format": "date-time", "title": "Must match run", "type": "string" }, "local_code_digest": { "title": "Must match approved definition unless override recorded", "type": "string" }, "local_record_count_bucket": { "enum": [ "lt_10", "10_49", "50_99", "100_499", "500_999", "1000_plus" ], "title": "Bucketed record count", "type": "string" }, "local_runner_version": { "title": "Runner or agent version", "type": "string" }, "local_subject_count_bucket": { "enum": [ "lt_10", "10_49", "50_99", "100_499", "500_999", "1000_plus" ], "title": "Required for person-affecting definitions", "type": "string" }, "participation_id": { "title": "Participation id", "type": "string" }, "payload_hash": { "title": "Required when payload_reference is set", "type": "string" }, "payload_reference": { "title": "Encrypted payload / clean-room output / secure aggregation share ref", "type": "string" }, "payload_size_bytes": { "title": "Safety bound", "type": "integer" }, "rejection_reason": { "title": "Bounded; required for rejected / suppressed", "type": "string" }, "result_status": { "enum": [ "accepted", "rejected", "suppressed" ], "title": "accepted | rejected | suppressed", "type": "string" }, "secure_aggregation_mask_ref": { "title": "Optional protocol metadata", "type": "string" }, "validation_warnings": { "items": { "type": "string" }, "title": "Local runner warnings", "type": "array" } }, "required": [ "participation_id", "contribution_kind", "local_code_digest", "local_runner_version", "input_snapshot_hash", "input_window_start", "input_window_end", "local_record_count_bucket", "clipping_applied", "result_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record federated contribution (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.record_federated_contribution/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_federated_contribution` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_federated_contribution:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_federated_contribution", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "attestation_reference": { "title": "TEE / runner attestation if used", "type": "string" }, "clipping_applied": { "title": "Required true for model updates", "type": "boolean" }, "contribution_kind": { "enum": [ "encrypted_aggregate", "noisy_aggregate", "model_update", "metrics_only", "attestation_only" ], "title": "Contribution kind", "type": "string" }, "contribution_slot": { "title": "Slot discriminator when definition declares multiple slots", "type": "string" }, "delta_spent": { "format": "decimal", "title": "Local DP spend", "type": "string" }, "epsilon_spent": { "format": "decimal", "title": "Local DP spend", "type": "string" }, "input_snapshot_hash": { "title": "Hash over local eligible input snapshot metadata", "type": "string" }, "input_window_end": { "format": "date-time", "title": "Must match run", "type": "string" }, "input_window_start": { "format": "date-time", "title": "Must match run", "type": "string" }, "local_code_digest": { "title": "Must match approved definition unless override recorded", "type": "string" }, "local_record_count_bucket": { "enum": [ "lt_10", "10_49", "50_99", "100_499", "500_999", "1000_plus" ], "title": "Bucketed record count", "type": "string" }, "local_runner_version": { "title": "Runner or agent version", "type": "string" }, "local_subject_count_bucket": { "enum": [ "lt_10", "10_49", "50_99", "100_499", "500_999", "1000_plus" ], "title": "Required for person-affecting definitions", "type": "string" }, "participation_id": { "title": "Participation id", "type": "string" }, "payload_hash": { "title": "Required when payload_reference is set", "type": "string" }, "payload_reference": { "title": "Encrypted payload / clean-room output / secure aggregation share ref", "type": "string" }, "payload_size_bytes": { "title": "Safety bound", "type": "integer" }, "rejection_reason": { "title": "Bounded; required for rejected / suppressed", "type": "string" }, "result_status": { "enum": [ "accepted", "rejected", "suppressed" ], "title": "accepted | rejected | suppressed", "type": "string" }, "secure_aggregation_mask_ref": { "title": "Optional protocol metadata", "type": "string" }, "validation_warnings": { "items": { "type": "string" }, "title": "Local runner warnings", "type": "array" } }, "required": [ "participation_id", "contribution_kind", "local_code_digest", "local_runner_version", "input_snapshot_hash", "input_window_start", "input_window_end", "local_record_count_bucket", "clipping_applied", "result_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_run" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record federated contribution (rollup delta)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.record_federated_privacy_incident/apply": { "post": { "description": "Record a privacy, security, or disclosure-control incident related to a program, run, contribution, or output. The handler appends an incident event, optionally quarantines outputs, and optionally pauses the program. Per proposal §8.13, the action creates the durable evidence trail but the remediation gate is opened separately through proposal 0020 approval gates.\n\nEffects: modify hospitality.federated_intelligence_program.", "operationId": "apply_hospitality_action_record_federated_privacy_incident", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "description": { "title": "Bounded text", "type": "string" }, "external_incident_reference": { "title": "External incident ref", "type": "string" }, "immediate_actions": { "title": "Bounded text describing immediate response (e.g. paused program X, quarantined output Y)", "type": "string" }, "incident_kind": { "enum": [ "disclosure_control_failure", "small_cohort_singling_out", "max_contributor_share_breach", "differencing_attack_suspected", "model_inversion_suspected", "membership_inference_suspected", "secure_aggregation_protocol_failure", "data_quality_poisoning_suspected", "legal_basis_change", "output_inference_attack", "other_reviewed" ], "title": "Incident kind", "type": "string" }, "pause_program": { "title": "If true, transitions program status to paused", "type": "boolean" }, "severity": { "enum": [ "informational", "low", "medium", "high", "critical" ], "title": "informational | low | medium | high | critical", "type": "string" }, "target_object_id": { "title": "Target object id", "type": "string" }, "target_object_type": { "title": "Program / run / contribution / output", "type": "string" } }, "required": [ "target_object_type", "target_object_id", "incident_kind", "severity", "description" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_intelligence_program" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.federated_intelligence_program" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_federated_privacy_incident:apply" ] } ], "summary": "Record federated privacy incident", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.record_federated_privacy_incident/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_federated_privacy_incident` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_federated_privacy_incident:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_federated_privacy_incident", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "description": { "title": "Bounded text", "type": "string" }, "external_incident_reference": { "title": "External incident ref", "type": "string" }, "immediate_actions": { "title": "Bounded text describing immediate response (e.g. paused program X, quarantined output Y)", "type": "string" }, "incident_kind": { "enum": [ "disclosure_control_failure", "small_cohort_singling_out", "max_contributor_share_breach", "differencing_attack_suspected", "model_inversion_suspected", "membership_inference_suspected", "secure_aggregation_protocol_failure", "data_quality_poisoning_suspected", "legal_basis_change", "output_inference_attack", "other_reviewed" ], "title": "Incident kind", "type": "string" }, "pause_program": { "title": "If true, transitions program status to paused", "type": "boolean" }, "severity": { "enum": [ "informational", "low", "medium", "high", "critical" ], "title": "informational | low | medium | high | critical", "type": "string" }, "target_object_id": { "title": "Target object id", "type": "string" }, "target_object_type": { "title": "Program / run / contribution / output", "type": "string" } }, "required": [ "target_object_type", "target_object_id", "incident_kind", "severity", "description" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_intelligence_program" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.federated_intelligence_program" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record federated privacy incident (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.record_federated_privacy_incident/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_federated_privacy_incident`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_federated_privacy_incident", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "description": { "title": "Bounded text", "type": "string" }, "external_incident_reference": { "title": "External incident ref", "type": "string" }, "immediate_actions": { "title": "Bounded text describing immediate response (e.g. paused program X, quarantined output Y)", "type": "string" }, "incident_kind": { "enum": [ "disclosure_control_failure", "small_cohort_singling_out", "max_contributor_share_breach", "differencing_attack_suspected", "model_inversion_suspected", "membership_inference_suspected", "secure_aggregation_protocol_failure", "data_quality_poisoning_suspected", "legal_basis_change", "output_inference_attack", "other_reviewed" ], "title": "Incident kind", "type": "string" }, "pause_program": { "title": "If true, transitions program status to paused", "type": "boolean" }, "severity": { "enum": [ "informational", "low", "medium", "high", "critical" ], "title": "informational | low | medium | high | critical", "type": "string" }, "target_object_id": { "title": "Target object id", "type": "string" }, "target_object_type": { "title": "Program / run / contribution / output", "type": "string" } }, "required": [ "target_object_type", "target_object_id", "incident_kind", "severity", "description" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_intelligence_program" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record federated privacy incident (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.record_federated_privacy_incident/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_federated_privacy_incident` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_federated_privacy_incident:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_federated_privacy_incident", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "description": { "title": "Bounded text", "type": "string" }, "external_incident_reference": { "title": "External incident ref", "type": "string" }, "immediate_actions": { "title": "Bounded text describing immediate response (e.g. paused program X, quarantined output Y)", "type": "string" }, "incident_kind": { "enum": [ "disclosure_control_failure", "small_cohort_singling_out", "max_contributor_share_breach", "differencing_attack_suspected", "model_inversion_suspected", "membership_inference_suspected", "secure_aggregation_protocol_failure", "data_quality_poisoning_suspected", "legal_basis_change", "output_inference_attack", "other_reviewed" ], "title": "Incident kind", "type": "string" }, "pause_program": { "title": "If true, transitions program status to paused", "type": "boolean" }, "severity": { "enum": [ "informational", "low", "medium", "high", "critical" ], "title": "informational | low | medium | high | critical", "type": "string" }, "target_object_id": { "title": "Target object id", "type": "string" }, "target_object_type": { "title": "Program / run / contribution / output", "type": "string" } }, "required": [ "target_object_type", "target_object_id", "incident_kind", "severity", "description" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_intelligence_program" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record federated privacy incident (rollup delta)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.record_function_event_actuals/apply": { "post": { "description": "After the function: record the actual attendance (and the set count, if not yet given) and move the event to `actual` — the status the banquet posting reads, because the billable count is the higher of the guarantee and the actual. Only a `definite` event can be actualised.\n\nEffects: modify hospitality.function_event.", "operationId": "apply_hospitality_action_record_function_event_actuals", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "actual_count": { "title": "Actual attendance", "type": "integer" }, "set_count": { "title": "How many the room was set for", "type": "integer" } }, "required": [ "actual_count" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_event" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.function_event" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_function_event_actuals:apply" ] } ], "summary": "Record function event actuals", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.record_function_event_actuals/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_function_event_actuals` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_function_event_actuals:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_function_event_actuals", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "actual_count": { "title": "Actual attendance", "type": "integer" }, "set_count": { "title": "How many the room was set for", "type": "integer" } }, "required": [ "actual_count" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_event" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.function_event" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record function event actuals (dry-run)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.record_function_event_actuals/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_function_event_actuals`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_function_event_actuals", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "actual_count": { "title": "Actual attendance", "type": "integer" }, "set_count": { "title": "How many the room was set for", "type": "integer" } }, "required": [ "actual_count" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_event" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record function event actuals (dry-run)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.record_function_event_actuals/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_function_event_actuals` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_function_event_actuals:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_function_event_actuals", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "actual_count": { "title": "Actual attendance", "type": "integer" }, "set_count": { "title": "How many the room was set for", "type": "integer" } }, "required": [ "actual_count" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_event" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record function event actuals (rollup delta)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.record_guest_feedback/apply": { "post": { "description": "Record what a guest told the house — a complaint, a compliment or a suggestion — as an `open` case at the target property. From a triaged message (`from_triage_id`, or the message itself as `message_id`): the feedback links the message, takes its guest, channel and time, and a `complaint.*` intent gives the kind and category (`complaint.noise` → complaint / noise). One feedback per message: recording the same message again with the same kind, category and text is a no-op, and with different ones is refused. From a stay (`stay_id`): the stay's guest is linked unless `person_id` names another. A complaint needs a category. `text` is the guest's words (or the desk's summary of them) and is marked as the guest's; the message's own excerpt is never copied. `delegate_to` hands the case to a role at once. Emits `guest_feedback.recorded`.\n\nEffects: create hospitality.guest_feedback; link hospitality.link.guest_feedback_for_stay; link hospitality.link.guest_feedback_for_person; link hospitality.link.guest_feedback_from_message.", "operationId": "apply_hospitality_action_record_guest_feedback", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "category": { "enum": [ "cleanliness", "noise", "billing", "service", "food", "maintenance", "other" ], "title": "What it is about (required on a complaint; derived from a complaint triage when absent)", "type": "string" }, "channel": { "enum": [ "in_person", "phone", "survey", "review", "sms", "whatsapp", "email", "web_chat", "app_chat", "voice_ivr", "ota_inbox", "social_dm", "in_room_device", "other" ], "title": "How it reached the house (defaults to the message's channel)", "type": "string" }, "delegate_to": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "The role to hand the case to on recording", "type": "string" }, "from_triage_id": { "format": "uuid", "title": "The triage of the message it was recorded from — its message is linked, and a complaint intent gives the kind and category", "type": "string", "x-aerandil-references": "hospitality.message_triage" }, "kind": { "enum": [ "complaint", "compliment", "suggestion" ], "title": "complaint, compliment or suggestion (derived from a complaint triage when absent)", "type": "string" }, "message_id": { "format": "uuid", "title": "The guest message it was recorded from", "type": "string", "x-aerandil-references": "hospitality.guest_message" }, "person_id": { "format": "uuid", "title": "The guest who gave it (defaults to the stay's or the message's guest)", "type": "string", "x-aerandil-references": "hospitality.person" }, "received_at": { "format": "date-time", "title": "When the guest gave it (defaults to the message's time, else now)", "type": "string" }, "stay_id": { "format": "uuid", "title": "The stay it is about", "type": "string", "x-aerandil-references": "hospitality.stay" }, "text": { "title": "What the guest said, in their words or the desk's summary", "type": "string" } }, "required": [ "text" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.guest_feedback_for_stay", "hospitality.link.guest_feedback_for_person", "hospitality.link.guest_feedback_from_message" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.guest_feedback" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_guest_feedback:apply" ] } ], "summary": "Record guest feedback", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_guest_feedback/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_guest_feedback` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_guest_feedback:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_guest_feedback", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "category": { "enum": [ "cleanliness", "noise", "billing", "service", "food", "maintenance", "other" ], "title": "What it is about (required on a complaint; derived from a complaint triage when absent)", "type": "string" }, "channel": { "enum": [ "in_person", "phone", "survey", "review", "sms", "whatsapp", "email", "web_chat", "app_chat", "voice_ivr", "ota_inbox", "social_dm", "in_room_device", "other" ], "title": "How it reached the house (defaults to the message's channel)", "type": "string" }, "delegate_to": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "The role to hand the case to on recording", "type": "string" }, "from_triage_id": { "format": "uuid", "title": "The triage of the message it was recorded from — its message is linked, and a complaint intent gives the kind and category", "type": "string", "x-aerandil-references": "hospitality.message_triage" }, "kind": { "enum": [ "complaint", "compliment", "suggestion" ], "title": "complaint, compliment or suggestion (derived from a complaint triage when absent)", "type": "string" }, "message_id": { "format": "uuid", "title": "The guest message it was recorded from", "type": "string", "x-aerandil-references": "hospitality.guest_message" }, "person_id": { "format": "uuid", "title": "The guest who gave it (defaults to the stay's or the message's guest)", "type": "string", "x-aerandil-references": "hospitality.person" }, "received_at": { "format": "date-time", "title": "When the guest gave it (defaults to the message's time, else now)", "type": "string" }, "stay_id": { "format": "uuid", "title": "The stay it is about", "type": "string", "x-aerandil-references": "hospitality.stay" }, "text": { "title": "What the guest said, in their words or the desk's summary", "type": "string" } }, "required": [ "text" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.guest_feedback_for_stay", "hospitality.link.guest_feedback_for_person", "hospitality.link.guest_feedback_from_message" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.guest_feedback" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record guest feedback (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_guest_feedback/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_guest_feedback`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_guest_feedback", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "category": { "enum": [ "cleanliness", "noise", "billing", "service", "food", "maintenance", "other" ], "title": "What it is about (required on a complaint; derived from a complaint triage when absent)", "type": "string" }, "channel": { "enum": [ "in_person", "phone", "survey", "review", "sms", "whatsapp", "email", "web_chat", "app_chat", "voice_ivr", "ota_inbox", "social_dm", "in_room_device", "other" ], "title": "How it reached the house (defaults to the message's channel)", "type": "string" }, "delegate_to": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "The role to hand the case to on recording", "type": "string" }, "from_triage_id": { "format": "uuid", "title": "The triage of the message it was recorded from — its message is linked, and a complaint intent gives the kind and category", "type": "string", "x-aerandil-references": "hospitality.message_triage" }, "kind": { "enum": [ "complaint", "compliment", "suggestion" ], "title": "complaint, compliment or suggestion (derived from a complaint triage when absent)", "type": "string" }, "message_id": { "format": "uuid", "title": "The guest message it was recorded from", "type": "string", "x-aerandil-references": "hospitality.guest_message" }, "person_id": { "format": "uuid", "title": "The guest who gave it (defaults to the stay's or the message's guest)", "type": "string", "x-aerandil-references": "hospitality.person" }, "received_at": { "format": "date-time", "title": "When the guest gave it (defaults to the message's time, else now)", "type": "string" }, "stay_id": { "format": "uuid", "title": "The stay it is about", "type": "string", "x-aerandil-references": "hospitality.stay" }, "text": { "title": "What the guest said, in their words or the desk's summary", "type": "string" } }, "required": [ "text" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record guest feedback (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_guest_feedback/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_guest_feedback` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_guest_feedback:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_guest_feedback", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "category": { "enum": [ "cleanliness", "noise", "billing", "service", "food", "maintenance", "other" ], "title": "What it is about (required on a complaint; derived from a complaint triage when absent)", "type": "string" }, "channel": { "enum": [ "in_person", "phone", "survey", "review", "sms", "whatsapp", "email", "web_chat", "app_chat", "voice_ivr", "ota_inbox", "social_dm", "in_room_device", "other" ], "title": "How it reached the house (defaults to the message's channel)", "type": "string" }, "delegate_to": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "The role to hand the case to on recording", "type": "string" }, "from_triage_id": { "format": "uuid", "title": "The triage of the message it was recorded from — its message is linked, and a complaint intent gives the kind and category", "type": "string", "x-aerandil-references": "hospitality.message_triage" }, "kind": { "enum": [ "complaint", "compliment", "suggestion" ], "title": "complaint, compliment or suggestion (derived from a complaint triage when absent)", "type": "string" }, "message_id": { "format": "uuid", "title": "The guest message it was recorded from", "type": "string", "x-aerandil-references": "hospitality.guest_message" }, "person_id": { "format": "uuid", "title": "The guest who gave it (defaults to the stay's or the message's guest)", "type": "string", "x-aerandil-references": "hospitality.person" }, "received_at": { "format": "date-time", "title": "When the guest gave it (defaults to the message's time, else now)", "type": "string" }, "stay_id": { "format": "uuid", "title": "The stay it is about", "type": "string", "x-aerandil-references": "hospitality.stay" }, "text": { "title": "What the guest said, in their words or the desk's summary", "type": "string" } }, "required": [ "text" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record guest feedback (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_guest_message/apply": { "post": { "description": "Record an inbound or outbound `guest_message` into Aerandil. Opens a `guest_conversation` lazily for the person at the property when none exists; appends the message; refreshes the conversation's denormalised counters. PCI-DSS hard validator gates `redacted_excerpt` against Luhn-matching sequences. WhatsApp 24-hour service-window validator gates outbound free-form messages without a `template_id`. Rejected if the conversation is in a closed state or if GDPR erasure has been requested in-thread. A reply the kernel composes — outbound into a named `conversation_id` with no `channel` — goes back on the channel and thread of the guest's most recent inbound message, to the conversation's person, and is refused when the guest opted out of that channel or asked for erasure; an outbound message given no `content_hash` is hashed from its excerpt (the kernel wrote it, so the excerpt is the whole message).\n\nEffects: create hospitality.guest_message; create hospitality.guest_conversation; modify hospitality.guest_conversation; link hospitality.link.guest_conversation_for_person; link hospitality.link.guest_conversation_at_property; link hospitality.link.guest_conversation_anchored_to_reservation; link hospitality.link.guest_message_in_conversation; link hospitality.link.guest_message_references_external_record.", "operationId": "apply_hospitality_action_record_guest_message", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "anchor_reservation_id": { "title": "Optional reservation anchor (sets `conversation.anchor_reservation_ref`)", "type": "string" }, "author_kind": { "enum": [ "guest", "staff_human", "staff_agent", "system" ], "title": "Author kind (guest / staff_human / staff_agent / system)", "type": "string" }, "author_principal": { "title": "`principal.stable_id()` of the author when not the guest", "type": "string" }, "channel": { "enum": [ "sms", "whatsapp", "email", "web_chat", "app_chat", "voice_ivr", "ota_inbox", "social_dm", "in_room_device", "other" ], "title": "Communication channel (a reply into a named conversation may omit it)", "type": "string" }, "channel_thread_id": { "title": "External system thread identifier (taken from the guest's last message on a reply)", "type": "string" }, "content_hash": { "title": "SHA-256 of the original message bytes (outbound: derived from the excerpt when absent)", "type": "string" }, "conversation_id": { "title": "Existing conversation to append to (handler opens one when absent)", "type": "string" }, "detected_language": { "title": "BCP-47 language tag", "type": "string" }, "direction": { "enum": [ "inbound", "outbound" ], "title": "inbound or outbound", "type": "string" }, "external_record_id": { "title": "Optional pointer to the external record reference", "type": "string" }, "language": { "title": "Initial language for new conversations (BCP-47)", "type": "string" }, "person_id": { "title": "The guest's person id (a reply into a named conversation takes the conversation's)", "type": "string" }, "received_at": { "format": "date-time", "title": "When the message arrived (inbound, required) or was sent (outbound; omitted = now, the kernel sending it)", "type": "string" }, "redacted_excerpt": { "title": "PII-stripped excerpt (default cap 280 chars)", "type": "string" }, "redactions_applied": { "items": { "enum": [ "pan", "cvv", "government_id", "health_disclosure", "child_safeguarding", "other_pii" ], "type": "string" }, "title": "Per-message redaction kinds", "type": "array" }, "template_id": { "title": "WhatsApp Business template id (required outside 24-hour window)", "type": "string" }, "word_count": { "title": "Optional word count", "type": "integer" } }, "required": [ "direction", "redacted_excerpt", "redactions_applied" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.guest_conversation_for_person", "hospitality.link.guest_conversation_at_property", "hospitality.link.guest_conversation_anchored_to_reservation", "hospitality.link.guest_message_in_conversation", "hospitality.link.guest_message_references_external_record" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.guest_message", "hospitality.guest_conversation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_guest_message:apply" ] } ], "summary": "Record guest message", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_guest_message/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_guest_message` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_guest_message:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_guest_message", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "anchor_reservation_id": { "title": "Optional reservation anchor (sets `conversation.anchor_reservation_ref`)", "type": "string" }, "author_kind": { "enum": [ "guest", "staff_human", "staff_agent", "system" ], "title": "Author kind (guest / staff_human / staff_agent / system)", "type": "string" }, "author_principal": { "title": "`principal.stable_id()` of the author when not the guest", "type": "string" }, "channel": { "enum": [ "sms", "whatsapp", "email", "web_chat", "app_chat", "voice_ivr", "ota_inbox", "social_dm", "in_room_device", "other" ], "title": "Communication channel (a reply into a named conversation may omit it)", "type": "string" }, "channel_thread_id": { "title": "External system thread identifier (taken from the guest's last message on a reply)", "type": "string" }, "content_hash": { "title": "SHA-256 of the original message bytes (outbound: derived from the excerpt when absent)", "type": "string" }, "conversation_id": { "title": "Existing conversation to append to (handler opens one when absent)", "type": "string" }, "detected_language": { "title": "BCP-47 language tag", "type": "string" }, "direction": { "enum": [ "inbound", "outbound" ], "title": "inbound or outbound", "type": "string" }, "external_record_id": { "title": "Optional pointer to the external record reference", "type": "string" }, "language": { "title": "Initial language for new conversations (BCP-47)", "type": "string" }, "person_id": { "title": "The guest's person id (a reply into a named conversation takes the conversation's)", "type": "string" }, "received_at": { "format": "date-time", "title": "When the message arrived (inbound, required) or was sent (outbound; omitted = now, the kernel sending it)", "type": "string" }, "redacted_excerpt": { "title": "PII-stripped excerpt (default cap 280 chars)", "type": "string" }, "redactions_applied": { "items": { "enum": [ "pan", "cvv", "government_id", "health_disclosure", "child_safeguarding", "other_pii" ], "type": "string" }, "title": "Per-message redaction kinds", "type": "array" }, "template_id": { "title": "WhatsApp Business template id (required outside 24-hour window)", "type": "string" }, "word_count": { "title": "Optional word count", "type": "integer" } }, "required": [ "direction", "redacted_excerpt", "redactions_applied" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.guest_conversation_for_person", "hospitality.link.guest_conversation_at_property", "hospitality.link.guest_conversation_anchored_to_reservation", "hospitality.link.guest_message_in_conversation", "hospitality.link.guest_message_references_external_record" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.guest_message", "hospitality.guest_conversation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record guest message (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_guest_message/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_guest_message`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_guest_message", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "anchor_reservation_id": { "title": "Optional reservation anchor (sets `conversation.anchor_reservation_ref`)", "type": "string" }, "author_kind": { "enum": [ "guest", "staff_human", "staff_agent", "system" ], "title": "Author kind (guest / staff_human / staff_agent / system)", "type": "string" }, "author_principal": { "title": "`principal.stable_id()` of the author when not the guest", "type": "string" }, "channel": { "enum": [ "sms", "whatsapp", "email", "web_chat", "app_chat", "voice_ivr", "ota_inbox", "social_dm", "in_room_device", "other" ], "title": "Communication channel (a reply into a named conversation may omit it)", "type": "string" }, "channel_thread_id": { "title": "External system thread identifier (taken from the guest's last message on a reply)", "type": "string" }, "content_hash": { "title": "SHA-256 of the original message bytes (outbound: derived from the excerpt when absent)", "type": "string" }, "conversation_id": { "title": "Existing conversation to append to (handler opens one when absent)", "type": "string" }, "detected_language": { "title": "BCP-47 language tag", "type": "string" }, "direction": { "enum": [ "inbound", "outbound" ], "title": "inbound or outbound", "type": "string" }, "external_record_id": { "title": "Optional pointer to the external record reference", "type": "string" }, "language": { "title": "Initial language for new conversations (BCP-47)", "type": "string" }, "person_id": { "title": "The guest's person id (a reply into a named conversation takes the conversation's)", "type": "string" }, "received_at": { "format": "date-time", "title": "When the message arrived (inbound, required) or was sent (outbound; omitted = now, the kernel sending it)", "type": "string" }, "redacted_excerpt": { "title": "PII-stripped excerpt (default cap 280 chars)", "type": "string" }, "redactions_applied": { "items": { "enum": [ "pan", "cvv", "government_id", "health_disclosure", "child_safeguarding", "other_pii" ], "type": "string" }, "title": "Per-message redaction kinds", "type": "array" }, "template_id": { "title": "WhatsApp Business template id (required outside 24-hour window)", "type": "string" }, "word_count": { "title": "Optional word count", "type": "integer" } }, "required": [ "direction", "redacted_excerpt", "redactions_applied" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record guest message (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_guest_message/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_guest_message` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_guest_message:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_guest_message", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "anchor_reservation_id": { "title": "Optional reservation anchor (sets `conversation.anchor_reservation_ref`)", "type": "string" }, "author_kind": { "enum": [ "guest", "staff_human", "staff_agent", "system" ], "title": "Author kind (guest / staff_human / staff_agent / system)", "type": "string" }, "author_principal": { "title": "`principal.stable_id()` of the author when not the guest", "type": "string" }, "channel": { "enum": [ "sms", "whatsapp", "email", "web_chat", "app_chat", "voice_ivr", "ota_inbox", "social_dm", "in_room_device", "other" ], "title": "Communication channel (a reply into a named conversation may omit it)", "type": "string" }, "channel_thread_id": { "title": "External system thread identifier (taken from the guest's last message on a reply)", "type": "string" }, "content_hash": { "title": "SHA-256 of the original message bytes (outbound: derived from the excerpt when absent)", "type": "string" }, "conversation_id": { "title": "Existing conversation to append to (handler opens one when absent)", "type": "string" }, "detected_language": { "title": "BCP-47 language tag", "type": "string" }, "direction": { "enum": [ "inbound", "outbound" ], "title": "inbound or outbound", "type": "string" }, "external_record_id": { "title": "Optional pointer to the external record reference", "type": "string" }, "language": { "title": "Initial language for new conversations (BCP-47)", "type": "string" }, "person_id": { "title": "The guest's person id (a reply into a named conversation takes the conversation's)", "type": "string" }, "received_at": { "format": "date-time", "title": "When the message arrived (inbound, required) or was sent (outbound; omitted = now, the kernel sending it)", "type": "string" }, "redacted_excerpt": { "title": "PII-stripped excerpt (default cap 280 chars)", "type": "string" }, "redactions_applied": { "items": { "enum": [ "pan", "cvv", "government_id", "health_disclosure", "child_safeguarding", "other_pii" ], "type": "string" }, "title": "Per-message redaction kinds", "type": "array" }, "template_id": { "title": "WhatsApp Business template id (required outside 24-hour window)", "type": "string" }, "word_count": { "title": "Optional word count", "type": "integer" } }, "required": [ "direction", "redacted_excerpt", "redactions_applied" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record guest message (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_housekeeping_task_entry/apply": { "post": { "description": "Add a line to a housekeeping task's thread — a `note` about this piece of work (\"guest asked for feather-free pillows\", \"stain by the window\"), as opposed to the day's briefing to the whole floor. A photo hangs off the line as an attachment (`host_kind = housekeeping_task_entry`). The author is the staff member behind the principal when there is one (a handset session), linked through `housekeeping_task_entry_recorded_by`; `recorded_by` names the principal either way. `recorded_at` defaults to now and takes the handset's own time when its offline queue sends the line later. Refused on a skipped task (its skip_reason says why); a finished task still takes notes. Replay-safe under the apply route's Idempotency-Key; a handset that mints the line's id (`entry_id`, a v4 or v7 UUID — so a photo taken offline can wait for the line) may send it again under a fresh key: the same words on the same task are a replay, anything else under that id is refused (409). Emits `housekeeping.task.entry_recorded` with the kind and the author, never the words.\n\nEffects: create hospitality.housekeeping_task_entry; link hospitality.link.housekeeping_task_entry_for_task; link hospitality.link.housekeeping_task_entry_recorded_by.", "operationId": "apply_hospitality_action_record_housekeeping_task_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "entry_id": { "title": "The line's id, when the handset minted it (a v4 or v7 UUID)", "type": "string" }, "kind": { "enum": [ "note" ], "title": "What the line records (defaults to note)", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When the line was written (defaults to now; a handset queueing offline sends its own time)", "type": "string" }, "text": { "title": "The words on the line (required for a note)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.housekeeping_task_entry_for_task", "hospitality.link.housekeeping_task_entry_recorded_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.housekeeping_task_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_housekeeping_task_entry:apply" ] } ], "summary": "Record housekeeping task entry", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.record_housekeeping_task_entry/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_housekeeping_task_entry` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_housekeeping_task_entry:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_housekeeping_task_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "entry_id": { "title": "The line's id, when the handset minted it (a v4 or v7 UUID)", "type": "string" }, "kind": { "enum": [ "note" ], "title": "What the line records (defaults to note)", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When the line was written (defaults to now; a handset queueing offline sends its own time)", "type": "string" }, "text": { "title": "The words on the line (required for a note)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.housekeeping_task_entry_for_task", "hospitality.link.housekeeping_task_entry_recorded_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.housekeeping_task_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record housekeeping task entry (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.record_housekeeping_task_entry/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_housekeeping_task_entry`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_housekeeping_task_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "entry_id": { "title": "The line's id, when the handset minted it (a v4 or v7 UUID)", "type": "string" }, "kind": { "enum": [ "note" ], "title": "What the line records (defaults to note)", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When the line was written (defaults to now; a handset queueing offline sends its own time)", "type": "string" }, "text": { "title": "The words on the line (required for a note)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record housekeeping task entry (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.record_housekeeping_task_entry/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_housekeeping_task_entry` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_housekeeping_task_entry:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_housekeeping_task_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "entry_id": { "title": "The line's id, when the handset minted it (a v4 or v7 UUID)", "type": "string" }, "kind": { "enum": [ "note" ], "title": "What the line records (defaults to note)", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When the line was written (defaults to now; a handset queueing offline sends its own time)", "type": "string" }, "text": { "title": "The words on the line (required for a note)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record housekeeping task entry (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.record_inference/apply": { "post": { "description": "Record an inference output with its full proposal 0026 `DataLineage` provenance envelope. The `lineage` parameter is the typed envelope (model_ref, training_cohort_id, source_events, source_objects, column_lineage, effective_consent, …); the handler validates it deserialises and that `source_events` is non-empty (a revocation sweep has nothing to key on otherwise), then emits `inference.recorded` with the envelope lifted into the indexed `events.lineage` column and the intersected `effective_consent` into `events.consent_scope`. Thin emitter: the training / serving pipeline that produced the inference lives outside the kernel (§6).", "operationId": "apply_hospitality_action_record_inference", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "lineage": { "additionalProperties": true, "title": "The typed DataLineage provenance envelope for this inference output", "type": "object" } }, "required": [ "lineage" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_inference:apply" ] } ], "summary": "Record inference", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.record_inference/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_inference` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_inference:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_inference", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "lineage": { "additionalProperties": true, "title": "The typed DataLineage provenance envelope for this inference output", "type": "object" } }, "required": [ "lineage" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record inference (dry-run)", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.record_inference/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_inference`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_inference", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "lineage": { "additionalProperties": true, "title": "The typed DataLineage provenance envelope for this inference output", "type": "object" } }, "required": [ "lineage" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record inference (dry-run)", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.record_inference/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_inference` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_inference:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_inference", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "lineage": { "additionalProperties": true, "title": "The typed DataLineage provenance envelope for this inference output", "type": "object" } }, "required": [ "lineage" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record inference (rollup delta)", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.record_ingredient_cost/apply": { "post": { "description": "Record a supplier-invoice cost as a per-property `ingredient_supplier_price` row. Closes the prior open row (`effective_to = new.effective_from`); the new row becomes the active price for the recipe pour-cost rollup. Downstream `refresh_recipe_pour_cost` is a separate flow.\n\nEffects: create hospitality.ingredient_supplier_price; modify hospitality.ingredient_supplier_price; link hospitality.link.ingredient_supplier_price_for_ingredient; link hospitality.link.ingredient_supplier_price_at_property.", "operationId": "apply_hospitality_action_record_ingredient_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cost": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Cost per canonical unit", "type": "object" }, "effective_from": { "format": "date-time", "title": "Effective from (defaults to received_at)", "type": "string" }, "invoice_reference": { "title": "Supplier invoice reference", "type": "string" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "received_at": { "format": "date-time", "title": "Received at (supplier invoice timestamp)", "type": "string" }, "supplier_code": { "title": "Supplier code", "type": "string" } }, "required": [ "property_id", "cost", "received_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.ingredient" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.ingredient_supplier_price_for_ingredient", "hospitality.link.ingredient_supplier_price_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.ingredient_supplier_price" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_ingredient_cost:apply" ] } ], "summary": "Record ingredient cost", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.record_ingredient_cost/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_ingredient_cost` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_ingredient_cost:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_ingredient_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cost": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Cost per canonical unit", "type": "object" }, "effective_from": { "format": "date-time", "title": "Effective from (defaults to received_at)", "type": "string" }, "invoice_reference": { "title": "Supplier invoice reference", "type": "string" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "received_at": { "format": "date-time", "title": "Received at (supplier invoice timestamp)", "type": "string" }, "supplier_code": { "title": "Supplier code", "type": "string" } }, "required": [ "property_id", "cost", "received_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.ingredient" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.ingredient_supplier_price_for_ingredient", "hospitality.link.ingredient_supplier_price_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.ingredient_supplier_price" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record ingredient cost (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.record_ingredient_cost/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_ingredient_cost`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_ingredient_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cost": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Cost per canonical unit", "type": "object" }, "effective_from": { "format": "date-time", "title": "Effective from (defaults to received_at)", "type": "string" }, "invoice_reference": { "title": "Supplier invoice reference", "type": "string" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "received_at": { "format": "date-time", "title": "Received at (supplier invoice timestamp)", "type": "string" }, "supplier_code": { "title": "Supplier code", "type": "string" } }, "required": [ "property_id", "cost", "received_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.ingredient" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record ingredient cost (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.record_ingredient_cost/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_ingredient_cost` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_ingredient_cost:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_ingredient_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "cost": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Cost per canonical unit", "type": "object" }, "effective_from": { "format": "date-time", "title": "Effective from (defaults to received_at)", "type": "string" }, "invoice_reference": { "title": "Supplier invoice reference", "type": "string" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "received_at": { "format": "date-time", "title": "Received at (supplier invoice timestamp)", "type": "string" }, "supplier_code": { "title": "Supplier code", "type": "string" } }, "required": [ "property_id", "cost", "received_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.ingredient" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record ingredient cost (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.record_labour_cost/apply": { "post": { "description": "Post one labour-cost amount from the payroll system of record — Aerandil never computes pay. Multi-day pay-period lines post to `business_date` un-prorated in v1; `period_start`/`period_end` preserve the source window. `external_ref` is the idempotency anchor for imports. Emits `labour.cost.recorded` for the `daily_labour` projection.\n\nEffects: create hospitality.labour_ledger_entry; link hospitality.link.labour_entry_at_property; link hospitality.link.labour_entry_for_staff_member; link hospitality.link.labour_entry_for_shift.", "operationId": "apply_hospitality_action_record_labour_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "business_date": { "format": "date", "title": "Accrual business date", "type": "string" }, "department": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "it_services", "retail", "other_operated", "minor_operated", "administrative_general", "information_telecom_systems", "sales_marketing", "property_ops_maintenance", "utilities" ], "title": "USALI 12 Schedule 15 department", "type": "string" }, "external_ref": { "title": "Payroll-system line id (idempotency anchor)", "type": "string" }, "kind": { "enum": [ "salaries_wages", "service_charges_distributed", "contracted_labour", "bonuses_incentives", "payroll_taxes", "supplemental_pay", "employee_benefits" ], "title": "USALI labour-cost kind", "type": "string" }, "period_end": { "format": "date", "title": "Pay-period end (optional)", "type": "string" }, "period_start": { "format": "date", "title": "Pay-period start (optional)", "type": "string" }, "shift_id": { "format": "uuid", "title": "Shift the accrual derives from (optional)", "type": "string", "x-aerandil-references": "hospitality.staff_shift" }, "source": { "enum": [ "timeclock", "payroll_import", "manual" ], "title": "Provenance (defaults to `payroll_import`)", "type": "string" }, "staff_member_id": { "format": "uuid", "title": "Staff member (optional — contracted labour and lump-sum imports may have none)", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "required": [ "kind", "department", "amount", "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.labour_entry_at_property", "hospitality.link.labour_entry_for_staff_member", "hospitality.link.labour_entry_for_shift" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.labour_ledger_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_labour_cost:apply" ] } ], "summary": "Record labour cost", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_labour_cost/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_labour_cost` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_labour_cost:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_labour_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "business_date": { "format": "date", "title": "Accrual business date", "type": "string" }, "department": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "it_services", "retail", "other_operated", "minor_operated", "administrative_general", "information_telecom_systems", "sales_marketing", "property_ops_maintenance", "utilities" ], "title": "USALI 12 Schedule 15 department", "type": "string" }, "external_ref": { "title": "Payroll-system line id (idempotency anchor)", "type": "string" }, "kind": { "enum": [ "salaries_wages", "service_charges_distributed", "contracted_labour", "bonuses_incentives", "payroll_taxes", "supplemental_pay", "employee_benefits" ], "title": "USALI labour-cost kind", "type": "string" }, "period_end": { "format": "date", "title": "Pay-period end (optional)", "type": "string" }, "period_start": { "format": "date", "title": "Pay-period start (optional)", "type": "string" }, "shift_id": { "format": "uuid", "title": "Shift the accrual derives from (optional)", "type": "string", "x-aerandil-references": "hospitality.staff_shift" }, "source": { "enum": [ "timeclock", "payroll_import", "manual" ], "title": "Provenance (defaults to `payroll_import`)", "type": "string" }, "staff_member_id": { "format": "uuid", "title": "Staff member (optional — contracted labour and lump-sum imports may have none)", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "required": [ "kind", "department", "amount", "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.labour_entry_at_property", "hospitality.link.labour_entry_for_staff_member", "hospitality.link.labour_entry_for_shift" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.labour_ledger_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record labour cost (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_labour_cost/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_labour_cost`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_labour_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "business_date": { "format": "date", "title": "Accrual business date", "type": "string" }, "department": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "it_services", "retail", "other_operated", "minor_operated", "administrative_general", "information_telecom_systems", "sales_marketing", "property_ops_maintenance", "utilities" ], "title": "USALI 12 Schedule 15 department", "type": "string" }, "external_ref": { "title": "Payroll-system line id (idempotency anchor)", "type": "string" }, "kind": { "enum": [ "salaries_wages", "service_charges_distributed", "contracted_labour", "bonuses_incentives", "payroll_taxes", "supplemental_pay", "employee_benefits" ], "title": "USALI labour-cost kind", "type": "string" }, "period_end": { "format": "date", "title": "Pay-period end (optional)", "type": "string" }, "period_start": { "format": "date", "title": "Pay-period start (optional)", "type": "string" }, "shift_id": { "format": "uuid", "title": "Shift the accrual derives from (optional)", "type": "string", "x-aerandil-references": "hospitality.staff_shift" }, "source": { "enum": [ "timeclock", "payroll_import", "manual" ], "title": "Provenance (defaults to `payroll_import`)", "type": "string" }, "staff_member_id": { "format": "uuid", "title": "Staff member (optional — contracted labour and lump-sum imports may have none)", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "required": [ "kind", "department", "amount", "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record labour cost (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_labour_cost/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_labour_cost` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_labour_cost:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_labour_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "business_date": { "format": "date", "title": "Accrual business date", "type": "string" }, "department": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "it_services", "retail", "other_operated", "minor_operated", "administrative_general", "information_telecom_systems", "sales_marketing", "property_ops_maintenance", "utilities" ], "title": "USALI 12 Schedule 15 department", "type": "string" }, "external_ref": { "title": "Payroll-system line id (idempotency anchor)", "type": "string" }, "kind": { "enum": [ "salaries_wages", "service_charges_distributed", "contracted_labour", "bonuses_incentives", "payroll_taxes", "supplemental_pay", "employee_benefits" ], "title": "USALI labour-cost kind", "type": "string" }, "period_end": { "format": "date", "title": "Pay-period end (optional)", "type": "string" }, "period_start": { "format": "date", "title": "Pay-period start (optional)", "type": "string" }, "shift_id": { "format": "uuid", "title": "Shift the accrual derives from (optional)", "type": "string", "x-aerandil-references": "hospitality.staff_shift" }, "source": { "enum": [ "timeclock", "payroll_import", "manual" ], "title": "Provenance (defaults to `payroll_import`)", "type": "string" }, "staff_member_id": { "format": "uuid", "title": "Staff member (optional — contracted labour and lump-sum imports may have none)", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "required": [ "kind", "department", "amount", "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record labour cost (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_lost_found_item/apply": { "post": { "description": "Record something found at the target property: what it is (never whose), where — `room_id` for a room of this property, or `found_location` for anywhere else — and when (`found_at`, defaulting to now). The staff member behind the principal (the handset's attendant or runner) is linked as the finder. The item is `found`, or `stored` at once when `storage_location` is given (the desk putting a handed-in phone straight in the safe). Its tag is the `id`: `LF-` and the last eight hex digits of the item's object id, upper-case. A caller may mint that object id itself (`item_id`, a v4 or v7 UUID) — a handset recording offline then knows the item, and the tag for the bag, before the record lands, and can hang the photo off it once it has; the same find under the same `item_id` again is a no-op, a different one is refused as a duplicate. Emits `lost_found_item.recorded`.\n\nEffects: create hospitality.lost_found_item; link hospitality.link.lost_found_item_in_room; link hospitality.link.lost_found_item_found_by.", "operationId": "apply_hospitality_action_record_lost_found_item", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "category": { "enum": [ "clothing", "electronics", "jewellery", "documents", "keys", "money", "toiletries", "other" ], "title": "What kind of thing it is", "type": "string" }, "description": { "title": "What it is — colour, make, distinguishing marks; not whose", "type": "string" }, "found_at": { "format": "date-time", "title": "When it was found (defaults to now)", "type": "string" }, "found_location": { "title": "Where it was found, when not in a room", "type": "string" }, "item_id": { "title": "The item's object id, when the caller mints it (a v4 or v7 UUID) — replay-safe: the same find again is a no-op", "type": "string" }, "room_id": { "format": "uuid", "title": "The room it was found in", "type": "string", "x-aerandil-references": "hospitality.room" }, "storage_location": { "title": "Where it is kept, when it is put away at once", "type": "string" } }, "required": [ "description" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.lost_found_item_in_room", "hospitality.link.lost_found_item_found_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.lost_found_item" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_lost_found_item:apply" ] } ], "summary": "Record lost & found item", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_lost_found_item/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_lost_found_item` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_lost_found_item:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_lost_found_item", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "category": { "enum": [ "clothing", "electronics", "jewellery", "documents", "keys", "money", "toiletries", "other" ], "title": "What kind of thing it is", "type": "string" }, "description": { "title": "What it is — colour, make, distinguishing marks; not whose", "type": "string" }, "found_at": { "format": "date-time", "title": "When it was found (defaults to now)", "type": "string" }, "found_location": { "title": "Where it was found, when not in a room", "type": "string" }, "item_id": { "title": "The item's object id, when the caller mints it (a v4 or v7 UUID) — replay-safe: the same find again is a no-op", "type": "string" }, "room_id": { "format": "uuid", "title": "The room it was found in", "type": "string", "x-aerandil-references": "hospitality.room" }, "storage_location": { "title": "Where it is kept, when it is put away at once", "type": "string" } }, "required": [ "description" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.lost_found_item_in_room", "hospitality.link.lost_found_item_found_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.lost_found_item" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record lost & found item (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_lost_found_item/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_lost_found_item`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_lost_found_item", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "category": { "enum": [ "clothing", "electronics", "jewellery", "documents", "keys", "money", "toiletries", "other" ], "title": "What kind of thing it is", "type": "string" }, "description": { "title": "What it is — colour, make, distinguishing marks; not whose", "type": "string" }, "found_at": { "format": "date-time", "title": "When it was found (defaults to now)", "type": "string" }, "found_location": { "title": "Where it was found, when not in a room", "type": "string" }, "item_id": { "title": "The item's object id, when the caller mints it (a v4 or v7 UUID) — replay-safe: the same find again is a no-op", "type": "string" }, "room_id": { "format": "uuid", "title": "The room it was found in", "type": "string", "x-aerandil-references": "hospitality.room" }, "storage_location": { "title": "Where it is kept, when it is put away at once", "type": "string" } }, "required": [ "description" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record lost & found item (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_lost_found_item/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_lost_found_item` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_lost_found_item:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_lost_found_item", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "category": { "enum": [ "clothing", "electronics", "jewellery", "documents", "keys", "money", "toiletries", "other" ], "title": "What kind of thing it is", "type": "string" }, "description": { "title": "What it is — colour, make, distinguishing marks; not whose", "type": "string" }, "found_at": { "format": "date-time", "title": "When it was found (defaults to now)", "type": "string" }, "found_location": { "title": "Where it was found, when not in a room", "type": "string" }, "item_id": { "title": "The item's object id, when the caller mints it (a v4 or v7 UUID) — replay-safe: the same find again is a no-op", "type": "string" }, "room_id": { "format": "uuid", "title": "The room it was found in", "type": "string", "x-aerandil-references": "hospitality.room" }, "storage_location": { "title": "Where it is kept, when it is put away at once", "type": "string" } }, "required": [ "description" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record lost & found item (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_pattern_recurrence_outcome/apply": { "post": { "description": "Record whether the failure pattern recurred in an observation window after remediation — the outcome signal that closes the detector's trust-formation loop.\n\nEffects: modify hospitality.service_recovery_pattern.", "operationId": "apply_hospitality_action_record_pattern_recurrence_outcome", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "recurrence_outcome": { "enum": [ "decayed_to_zero", "decayed_significantly", "decayed_partially", "unchanged", "worsened", "not_measurable" ], "title": "Observed recurrence state", "type": "string" }, "recurrence_outcome_event_count": { "title": "Event count in the outcome window", "type": "integer" }, "recurrence_outcome_window_end": { "format": "date-time", "title": "Outcome window end", "type": "string" }, "recurrence_outcome_window_start": { "format": "date-time", "title": "Outcome window start", "type": "string" } }, "required": [ "recurrence_outcome", "recurrence_outcome_window_start", "recurrence_outcome_window_end", "recurrence_outcome_event_count" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_recovery_pattern" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.service_recovery_pattern" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_pattern_recurrence_outcome:apply" ] } ], "summary": "Record pattern recurrence outcome", "tags": [ "recovery_pattern_detection" ] } }, "/v1/actions/hospitality.action.record_pattern_recurrence_outcome/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_pattern_recurrence_outcome` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_pattern_recurrence_outcome:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_pattern_recurrence_outcome", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "recurrence_outcome": { "enum": [ "decayed_to_zero", "decayed_significantly", "decayed_partially", "unchanged", "worsened", "not_measurable" ], "title": "Observed recurrence state", "type": "string" }, "recurrence_outcome_event_count": { "title": "Event count in the outcome window", "type": "integer" }, "recurrence_outcome_window_end": { "format": "date-time", "title": "Outcome window end", "type": "string" }, "recurrence_outcome_window_start": { "format": "date-time", "title": "Outcome window start", "type": "string" } }, "required": [ "recurrence_outcome", "recurrence_outcome_window_start", "recurrence_outcome_window_end", "recurrence_outcome_event_count" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_recovery_pattern" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.service_recovery_pattern" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record pattern recurrence outcome (dry-run)", "tags": [ "recovery_pattern_detection" ] } }, "/v1/actions/hospitality.action.record_pattern_recurrence_outcome/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_pattern_recurrence_outcome`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_pattern_recurrence_outcome", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "recurrence_outcome": { "enum": [ "decayed_to_zero", "decayed_significantly", "decayed_partially", "unchanged", "worsened", "not_measurable" ], "title": "Observed recurrence state", "type": "string" }, "recurrence_outcome_event_count": { "title": "Event count in the outcome window", "type": "integer" }, "recurrence_outcome_window_end": { "format": "date-time", "title": "Outcome window end", "type": "string" }, "recurrence_outcome_window_start": { "format": "date-time", "title": "Outcome window start", "type": "string" } }, "required": [ "recurrence_outcome", "recurrence_outcome_window_start", "recurrence_outcome_window_end", "recurrence_outcome_event_count" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_recovery_pattern" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record pattern recurrence outcome (dry-run)", "tags": [ "recovery_pattern_detection" ] } }, "/v1/actions/hospitality.action.record_pattern_recurrence_outcome/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_pattern_recurrence_outcome` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_pattern_recurrence_outcome:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_pattern_recurrence_outcome", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "recurrence_outcome": { "enum": [ "decayed_to_zero", "decayed_significantly", "decayed_partially", "unchanged", "worsened", "not_measurable" ], "title": "Observed recurrence state", "type": "string" }, "recurrence_outcome_event_count": { "title": "Event count in the outcome window", "type": "integer" }, "recurrence_outcome_window_end": { "format": "date-time", "title": "Outcome window end", "type": "string" }, "recurrence_outcome_window_start": { "format": "date-time", "title": "Outcome window start", "type": "string" } }, "required": [ "recurrence_outcome", "recurrence_outcome_window_start", "recurrence_outcome_window_end", "recurrence_outcome_event_count" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_recovery_pattern" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record pattern recurrence outcome (rollup delta)", "tags": [ "recovery_pattern_detection" ] } }, "/v1/actions/hospitality.action.record_payment_dispute/apply": { "post": { "description": "Mirror a chargeback's current state from the processor onto the payment it contests. Upserts on `psp_dispute_reference`: the first call mints the dispute and links it, later calls advance it, so every processor event about one case routes here and replay is a no-op. **The kernel does not own this state machine.** The card network decides a dispute and the processor reports it, so there is deliberately no guard on which transition is legal — `lost` to `won` really happens (Stripe's \"late win\", where an issuer moves money outside the normal lifecycle months later), and refusing it would leave the kernel insisting on a balance the bank disagrees with. What *is* guarded is staleness. Webhook delivery is not ordered, so `observed_at` is checked against the case's `last_observed_at` and an older view is dropped rather than allowed to regress a decided case. Money is already gone by the time the first call lands: the network debits the disputed amount plus a non-refundable fee when the case opens. `funds_reinstated_at` is the only field that says it came back. **A lost case reaches the ledger.** On the move into `lost` the payment is reversed on its bill: a settled refund leg (`refund_reason = chargeback_lost`, capped at what the payment still has unrefunded) lands beside the original, on its folio (or the open rebate folio of a sealed one, or the booking), and the folio's balance moves by it — the money the guest took back is owed again. Once per case. The network's fee (`dispute_fee`, net of what a win returned) is recorded on the case, never on the guest's bill: it is the merchant's cost, and on a hotel's own account the card rail passes it to the hotel at cost. A late win (`lost` to `won`) fails the leg and puts the balance back. **An inquiry escalated to a chargeback** (an inquiry state to `needs_response`) takes evidence again: the case records `escalated_at`, moves the inquiry's `evidence_submitted_at` to `inquiry_evidence_submitted_at` and keeps the processor's count then as `inquiry_submission_count` (the chargeback's own submission is counted above it), and a packet submitted for the inquiry is kept as `superseded_by_escalation`. The CE 3.0 facts (`card_brand`, `network_reason_code`, `visa_ce3_status`, `visa_ce3_required_actions`) are mirrored when the view carries them.\n\nEffects: create hospitality.payment_dispute; modify hospitality.payment_dispute; link hospitality.link.dispute_for_payment; create hospitality.payment; modify hospitality.payment; link hospitality.link.folio_has_payment; link hospitality.link.payment_refunds_payment; link hospitality.link.payment_for_reservation; modify hospitality.folio; modify hospitality.reservation; modify hospitality.dispute_evidence_packet.", "operationId": "apply_hospitality_action_record_payment_dispute", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Disputed amount", "type": "object" }, "card_brand": { "title": "The disputed card's brand as the processor reports it", "type": "string" }, "charge_still_refundable": { "title": "Whether the disputed payment can still be refunded", "type": "boolean" }, "closed_at": { "format": "date-time", "title": "Closed at", "type": "string" }, "dispute_fee": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "What the processor charged for the case, net of any fee a win returned", "type": "object" }, "evidence_due_by": { "format": "date-time", "title": "Evidence deadline", "type": "string" }, "evidence_past_due": { "title": "Whether the last submission reached the processor after the deadline", "type": "boolean" }, "evidence_submitted_at": { "format": "date-time", "title": "Evidence submitted at", "type": "string" }, "funds_reinstated_at": { "format": "date-time", "title": "Funds reinstated at", "type": "string" }, "funds_withdrawn_at": { "format": "date-time", "title": "Funds withdrawn at", "type": "string" }, "has_evidence": { "title": "Whether the processor holds evidence for the case (staged or submitted)", "type": "boolean" }, "network_reason_code": { "title": "The card network's reason code for the case", "type": "string" }, "observed_at": { "format": "date-time", "title": "When the processor reported this state (the event's own timestamp, never the time of the call)", "type": "string" }, "opened_at": { "format": "date-time", "title": "Opened at", "type": "string" }, "psp_dispute_reference": { "title": "The processor's own id for the case — the upsert key", "type": "string" }, "reason": { "enum": [ "bank_cannot_process", "check_returned", "credit_not_processed", "customer_initiated", "debit_not_authorized", "duplicate", "fraudulent", "general", "incorrect_account_details", "insufficient_funds", "noncompliant", "product_not_received", "product_unacceptable", "subscription_canceled", "unrecognized" ], "title": "Reason", "type": "string" }, "status": { "enum": [ "inquiry_needs_response", "inquiry_under_review", "inquiry_closed", "needs_response", "under_review", "won", "lost", "prevented" ], "title": "Status", "type": "string" }, "submission_count": { "title": "Evidence submission count", "type": "integer" }, "visa_ce3_required_actions": { "items": { "enum": [ "missing_customer_identifiers", "missing_disputed_transaction_description", "missing_merchandise_or_services", "missing_prior_undisputed_transaction_description", "missing_prior_undisputed_transactions" ], "type": "string" }, "title": "What the processor says the case still lacks for Visa CE 3.0", "type": "array" }, "visa_ce3_status": { "enum": [ "requires_action", "qualified", "not_qualified" ], "title": "The processor's Visa Compelling Evidence 3.0 status for the case", "type": "string" } }, "required": [ "psp_dispute_reference", "observed_at", "status", "reason", "amount", "opened_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.dispute_for_payment", "hospitality.link.folio_has_payment", "hospitality.link.payment_refunds_payment", "hospitality.link.payment_for_reservation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.payment_dispute", "hospitality.payment", "hospitality.folio", "hospitality.reservation", "hospitality.dispute_evidence_packet" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_payment_dispute:apply" ] } ], "summary": "Record payment dispute", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.record_payment_dispute/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_payment_dispute` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_payment_dispute:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_payment_dispute", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Disputed amount", "type": "object" }, "card_brand": { "title": "The disputed card's brand as the processor reports it", "type": "string" }, "charge_still_refundable": { "title": "Whether the disputed payment can still be refunded", "type": "boolean" }, "closed_at": { "format": "date-time", "title": "Closed at", "type": "string" }, "dispute_fee": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "What the processor charged for the case, net of any fee a win returned", "type": "object" }, "evidence_due_by": { "format": "date-time", "title": "Evidence deadline", "type": "string" }, "evidence_past_due": { "title": "Whether the last submission reached the processor after the deadline", "type": "boolean" }, "evidence_submitted_at": { "format": "date-time", "title": "Evidence submitted at", "type": "string" }, "funds_reinstated_at": { "format": "date-time", "title": "Funds reinstated at", "type": "string" }, "funds_withdrawn_at": { "format": "date-time", "title": "Funds withdrawn at", "type": "string" }, "has_evidence": { "title": "Whether the processor holds evidence for the case (staged or submitted)", "type": "boolean" }, "network_reason_code": { "title": "The card network's reason code for the case", "type": "string" }, "observed_at": { "format": "date-time", "title": "When the processor reported this state (the event's own timestamp, never the time of the call)", "type": "string" }, "opened_at": { "format": "date-time", "title": "Opened at", "type": "string" }, "psp_dispute_reference": { "title": "The processor's own id for the case — the upsert key", "type": "string" }, "reason": { "enum": [ "bank_cannot_process", "check_returned", "credit_not_processed", "customer_initiated", "debit_not_authorized", "duplicate", "fraudulent", "general", "incorrect_account_details", "insufficient_funds", "noncompliant", "product_not_received", "product_unacceptable", "subscription_canceled", "unrecognized" ], "title": "Reason", "type": "string" }, "status": { "enum": [ "inquiry_needs_response", "inquiry_under_review", "inquiry_closed", "needs_response", "under_review", "won", "lost", "prevented" ], "title": "Status", "type": "string" }, "submission_count": { "title": "Evidence submission count", "type": "integer" }, "visa_ce3_required_actions": { "items": { "enum": [ "missing_customer_identifiers", "missing_disputed_transaction_description", "missing_merchandise_or_services", "missing_prior_undisputed_transaction_description", "missing_prior_undisputed_transactions" ], "type": "string" }, "title": "What the processor says the case still lacks for Visa CE 3.0", "type": "array" }, "visa_ce3_status": { "enum": [ "requires_action", "qualified", "not_qualified" ], "title": "The processor's Visa Compelling Evidence 3.0 status for the case", "type": "string" } }, "required": [ "psp_dispute_reference", "observed_at", "status", "reason", "amount", "opened_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.dispute_for_payment", "hospitality.link.folio_has_payment", "hospitality.link.payment_refunds_payment", "hospitality.link.payment_for_reservation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.payment_dispute", "hospitality.payment", "hospitality.folio", "hospitality.reservation", "hospitality.dispute_evidence_packet" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record payment dispute (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.record_payment_dispute/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_payment_dispute`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_payment_dispute", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Disputed amount", "type": "object" }, "card_brand": { "title": "The disputed card's brand as the processor reports it", "type": "string" }, "charge_still_refundable": { "title": "Whether the disputed payment can still be refunded", "type": "boolean" }, "closed_at": { "format": "date-time", "title": "Closed at", "type": "string" }, "dispute_fee": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "What the processor charged for the case, net of any fee a win returned", "type": "object" }, "evidence_due_by": { "format": "date-time", "title": "Evidence deadline", "type": "string" }, "evidence_past_due": { "title": "Whether the last submission reached the processor after the deadline", "type": "boolean" }, "evidence_submitted_at": { "format": "date-time", "title": "Evidence submitted at", "type": "string" }, "funds_reinstated_at": { "format": "date-time", "title": "Funds reinstated at", "type": "string" }, "funds_withdrawn_at": { "format": "date-time", "title": "Funds withdrawn at", "type": "string" }, "has_evidence": { "title": "Whether the processor holds evidence for the case (staged or submitted)", "type": "boolean" }, "network_reason_code": { "title": "The card network's reason code for the case", "type": "string" }, "observed_at": { "format": "date-time", "title": "When the processor reported this state (the event's own timestamp, never the time of the call)", "type": "string" }, "opened_at": { "format": "date-time", "title": "Opened at", "type": "string" }, "psp_dispute_reference": { "title": "The processor's own id for the case — the upsert key", "type": "string" }, "reason": { "enum": [ "bank_cannot_process", "check_returned", "credit_not_processed", "customer_initiated", "debit_not_authorized", "duplicate", "fraudulent", "general", "incorrect_account_details", "insufficient_funds", "noncompliant", "product_not_received", "product_unacceptable", "subscription_canceled", "unrecognized" ], "title": "Reason", "type": "string" }, "status": { "enum": [ "inquiry_needs_response", "inquiry_under_review", "inquiry_closed", "needs_response", "under_review", "won", "lost", "prevented" ], "title": "Status", "type": "string" }, "submission_count": { "title": "Evidence submission count", "type": "integer" }, "visa_ce3_required_actions": { "items": { "enum": [ "missing_customer_identifiers", "missing_disputed_transaction_description", "missing_merchandise_or_services", "missing_prior_undisputed_transaction_description", "missing_prior_undisputed_transactions" ], "type": "string" }, "title": "What the processor says the case still lacks for Visa CE 3.0", "type": "array" }, "visa_ce3_status": { "enum": [ "requires_action", "qualified", "not_qualified" ], "title": "The processor's Visa Compelling Evidence 3.0 status for the case", "type": "string" } }, "required": [ "psp_dispute_reference", "observed_at", "status", "reason", "amount", "opened_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record payment dispute (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.record_payment_dispute/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_payment_dispute` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_payment_dispute:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_payment_dispute", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Disputed amount", "type": "object" }, "card_brand": { "title": "The disputed card's brand as the processor reports it", "type": "string" }, "charge_still_refundable": { "title": "Whether the disputed payment can still be refunded", "type": "boolean" }, "closed_at": { "format": "date-time", "title": "Closed at", "type": "string" }, "dispute_fee": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "What the processor charged for the case, net of any fee a win returned", "type": "object" }, "evidence_due_by": { "format": "date-time", "title": "Evidence deadline", "type": "string" }, "evidence_past_due": { "title": "Whether the last submission reached the processor after the deadline", "type": "boolean" }, "evidence_submitted_at": { "format": "date-time", "title": "Evidence submitted at", "type": "string" }, "funds_reinstated_at": { "format": "date-time", "title": "Funds reinstated at", "type": "string" }, "funds_withdrawn_at": { "format": "date-time", "title": "Funds withdrawn at", "type": "string" }, "has_evidence": { "title": "Whether the processor holds evidence for the case (staged or submitted)", "type": "boolean" }, "network_reason_code": { "title": "The card network's reason code for the case", "type": "string" }, "observed_at": { "format": "date-time", "title": "When the processor reported this state (the event's own timestamp, never the time of the call)", "type": "string" }, "opened_at": { "format": "date-time", "title": "Opened at", "type": "string" }, "psp_dispute_reference": { "title": "The processor's own id for the case — the upsert key", "type": "string" }, "reason": { "enum": [ "bank_cannot_process", "check_returned", "credit_not_processed", "customer_initiated", "debit_not_authorized", "duplicate", "fraudulent", "general", "incorrect_account_details", "insufficient_funds", "noncompliant", "product_not_received", "product_unacceptable", "subscription_canceled", "unrecognized" ], "title": "Reason", "type": "string" }, "status": { "enum": [ "inquiry_needs_response", "inquiry_under_review", "inquiry_closed", "needs_response", "under_review", "won", "lost", "prevented" ], "title": "Status", "type": "string" }, "submission_count": { "title": "Evidence submission count", "type": "integer" }, "visa_ce3_required_actions": { "items": { "enum": [ "missing_customer_identifiers", "missing_disputed_transaction_description", "missing_merchandise_or_services", "missing_prior_undisputed_transaction_description", "missing_prior_undisputed_transactions" ], "type": "string" }, "title": "What the processor says the case still lacks for Visa CE 3.0", "type": "array" }, "visa_ce3_status": { "enum": [ "requires_action", "qualified", "not_qualified" ], "title": "The processor's Visa Compelling Evidence 3.0 status for the case", "type": "string" } }, "required": [ "psp_dispute_reference", "observed_at", "status", "reason", "amount", "opened_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record payment dispute (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.record_recognition_event/apply": { "post": { "description": "Log a recognition event against the target property. Always-on across all loyalty archetypes — the program_type does not gate recognition. The program reference is optional because recognition-only patterns without a formal program record events without a program ref. The pair with record_service_recovery lets the operator's recognition-vs- recovery balance surface as a structural read about the property's hospitality character.\n\nEffects: create hospitality.recognition_event; link hospitality.link.recognition_event_for_person; link hospitality.link.recognition_event_for_program; link hospitality.link.recognition_event_at_property.", "operationId": "apply_hospitality_action_record_recognition_event", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "comp_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Comp amount", "type": "object" }, "comp_category": { "title": "Comp category (toolkit dictionary key)", "type": "string" }, "delivery_visibility": { "enum": [ "visible_to_guest", "invisible_to_guest" ], "title": "Delivery visibility", "type": "string" }, "happened_at": { "format": "date-time", "title": "When the recognition happened", "type": "string" }, "person_id": { "format": "uuid", "title": "Person being recognised", "type": "string", "x-aerandil-references": "hospitality.person" }, "program_id": { "format": "uuid", "title": "Loyalty program (optional — recognition-only patterns may omit)", "type": "string", "x-aerandil-references": "hospitality.loyalty_program" }, "recogniser": { "title": "Recogniser principal identifier", "type": "string" }, "recognition_action_text": { "title": "What the operator did", "type": "string" }, "recognition_kind": { "enum": [ "name_acknowledged", "preference_anticipated", "relationship_remembered", "gesture_offered", "upgrade_provided", "amenity_provided", "personal_note_left", "birthday_anniversary_marked", "repeat_visit_acknowledged", "vip_treatment_initiated", "other" ], "title": "Recognition kind", "type": "string" }, "recognition_subject_text": { "title": "What was recognised", "type": "string" }, "stay_id": { "title": "Stay context (when applicable)", "type": "string" } }, "required": [ "person_id", "recognition_kind", "delivery_visibility", "recogniser", "happened_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.recognition_event_for_person", "hospitality.link.recognition_event_for_program", "hospitality.link.recognition_event_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.recognition_event" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_recognition_event:apply" ] } ], "summary": "Record recognition event", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_recognition_event/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_recognition_event` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_recognition_event:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_recognition_event", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "comp_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Comp amount", "type": "object" }, "comp_category": { "title": "Comp category (toolkit dictionary key)", "type": "string" }, "delivery_visibility": { "enum": [ "visible_to_guest", "invisible_to_guest" ], "title": "Delivery visibility", "type": "string" }, "happened_at": { "format": "date-time", "title": "When the recognition happened", "type": "string" }, "person_id": { "format": "uuid", "title": "Person being recognised", "type": "string", "x-aerandil-references": "hospitality.person" }, "program_id": { "format": "uuid", "title": "Loyalty program (optional — recognition-only patterns may omit)", "type": "string", "x-aerandil-references": "hospitality.loyalty_program" }, "recogniser": { "title": "Recogniser principal identifier", "type": "string" }, "recognition_action_text": { "title": "What the operator did", "type": "string" }, "recognition_kind": { "enum": [ "name_acknowledged", "preference_anticipated", "relationship_remembered", "gesture_offered", "upgrade_provided", "amenity_provided", "personal_note_left", "birthday_anniversary_marked", "repeat_visit_acknowledged", "vip_treatment_initiated", "other" ], "title": "Recognition kind", "type": "string" }, "recognition_subject_text": { "title": "What was recognised", "type": "string" }, "stay_id": { "title": "Stay context (when applicable)", "type": "string" } }, "required": [ "person_id", "recognition_kind", "delivery_visibility", "recogniser", "happened_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.recognition_event_for_person", "hospitality.link.recognition_event_for_program", "hospitality.link.recognition_event_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.recognition_event" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record recognition event (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_recognition_event/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_recognition_event`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_recognition_event", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "comp_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Comp amount", "type": "object" }, "comp_category": { "title": "Comp category (toolkit dictionary key)", "type": "string" }, "delivery_visibility": { "enum": [ "visible_to_guest", "invisible_to_guest" ], "title": "Delivery visibility", "type": "string" }, "happened_at": { "format": "date-time", "title": "When the recognition happened", "type": "string" }, "person_id": { "format": "uuid", "title": "Person being recognised", "type": "string", "x-aerandil-references": "hospitality.person" }, "program_id": { "format": "uuid", "title": "Loyalty program (optional — recognition-only patterns may omit)", "type": "string", "x-aerandil-references": "hospitality.loyalty_program" }, "recogniser": { "title": "Recogniser principal identifier", "type": "string" }, "recognition_action_text": { "title": "What the operator did", "type": "string" }, "recognition_kind": { "enum": [ "name_acknowledged", "preference_anticipated", "relationship_remembered", "gesture_offered", "upgrade_provided", "amenity_provided", "personal_note_left", "birthday_anniversary_marked", "repeat_visit_acknowledged", "vip_treatment_initiated", "other" ], "title": "Recognition kind", "type": "string" }, "recognition_subject_text": { "title": "What was recognised", "type": "string" }, "stay_id": { "title": "Stay context (when applicable)", "type": "string" } }, "required": [ "person_id", "recognition_kind", "delivery_visibility", "recogniser", "happened_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record recognition event (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_recognition_event/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_recognition_event` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_recognition_event:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_recognition_event", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "comp_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Comp amount", "type": "object" }, "comp_category": { "title": "Comp category (toolkit dictionary key)", "type": "string" }, "delivery_visibility": { "enum": [ "visible_to_guest", "invisible_to_guest" ], "title": "Delivery visibility", "type": "string" }, "happened_at": { "format": "date-time", "title": "When the recognition happened", "type": "string" }, "person_id": { "format": "uuid", "title": "Person being recognised", "type": "string", "x-aerandil-references": "hospitality.person" }, "program_id": { "format": "uuid", "title": "Loyalty program (optional — recognition-only patterns may omit)", "type": "string", "x-aerandil-references": "hospitality.loyalty_program" }, "recogniser": { "title": "Recogniser principal identifier", "type": "string" }, "recognition_action_text": { "title": "What the operator did", "type": "string" }, "recognition_kind": { "enum": [ "name_acknowledged", "preference_anticipated", "relationship_remembered", "gesture_offered", "upgrade_provided", "amenity_provided", "personal_note_left", "birthday_anniversary_marked", "repeat_visit_acknowledged", "vip_treatment_initiated", "other" ], "title": "Recognition kind", "type": "string" }, "recognition_subject_text": { "title": "What was recognised", "type": "string" }, "stay_id": { "title": "Stay context (when applicable)", "type": "string" } }, "required": [ "person_id", "recognition_kind", "delivery_visibility", "recogniser", "happened_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record recognition event (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_service_recovery/apply": { "post": { "description": "Log a service-recovery event against the target venue. The comp_authority_snapshot freezes the toolkit's role rules at recovery time so a later toolkit edit doesn't retroactively re-evaluate authorisation. Soft validators warn on over-limit comp but never block — over-limit recoveries are the data the operator most needs and would otherwise hide.\n\nEffects: create hospitality.service_recovery_event; link hospitality.link.recovery_event_for_person; link hospitality.link.recovery_event_in_venue.", "operationId": "apply_hospitality_action_record_service_recovery", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "comp_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Comp amount", "type": "object" }, "comp_authority_snapshot": { "properties": { "comp_categories_allowed_at_recovery": { "items": { "enum": [ "room_night", "food_beverage", "spa", "retail", "parking", "other" ], "type": "string" }, "type": "array" }, "flat_universal_per_incident_limit_at_recovery": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "per_incident_limit_at_recovery": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "per_shift_cumulative_at_recovery": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "policy_kind_at_recovery": { "type": "string" }, "role_code_at_recovery": { "type": "string" } }, "required": [ "policy_kind_at_recovery" ], "title": "Frozen comp authority snapshot", "type": "object" }, "comp_category": { "enum": [ "room_night", "food_beverage", "spa", "retail", "parking", "other" ], "title": "Comp category", "type": "string" }, "failure_category": { "enum": [ "staff_interaction", "room_condition", "fnb_quality", "fnb_service_pace", "billing", "allergy_dietary", "security_safety", "check_in_out", "maintenance", "recognition_failure", "anticipation_miss", "noise", "temperature", "other" ], "title": "Failure category", "type": "string" }, "failure_subject_text": { "title": "What went wrong", "type": "string" }, "follow_up_due_at": { "format": "date-time", "title": "Follow-up due", "type": "string" }, "happened_at": { "format": "date-time", "title": "When the failure happened", "type": "string" }, "interactional_quality": { "enum": [ "failed", "adequate", "genuine", "excellent" ], "title": "How the recovery landed", "type": "string" }, "person_id": { "format": "uuid", "title": "Person who experienced the failure", "type": "string", "x-aerandil-references": "hospitality.person" }, "recovery_action_category": { "enum": [ "apology_only", "apology_plus_gesture", "apology_plus_comp", "apology_plus_upgrade", "complaint_handling_only", "gesture_declined_with_dignity", "escalated_unresolved" ], "title": "Recovery action category", "type": "string" }, "recovery_authoriser": { "title": "Authoriser principal identifier", "type": "string" }, "recovery_process_stages_completed": { "items": { "enum": [ "aware", "acknowledge", "apologise", "act", "additional_generosity" ], "type": "string" }, "title": "USHG 5 As stages completed", "type": "array" }, "severity": { "enum": [ "minor", "moderate", "significant", "severe", "safety_health" ], "title": "Severity", "type": "string" }, "time_to_first_response_seconds": { "title": "Seconds until first response", "type": "integer" }, "time_to_resolution_seconds": { "title": "Seconds until resolved", "type": "integer" } }, "required": [ "person_id", "failure_category", "severity", "failure_subject_text", "recovery_action_category", "recovery_process_stages_completed", "comp_authority_snapshot", "recovery_authoriser", "happened_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.recovery_event_for_person", "hospitality.link.recovery_event_in_venue" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.service_recovery_event" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_service_recovery:apply" ] } ], "summary": "Record service recovery", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_service_recovery/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_service_recovery` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_service_recovery:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_service_recovery", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "comp_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Comp amount", "type": "object" }, "comp_authority_snapshot": { "properties": { "comp_categories_allowed_at_recovery": { "items": { "enum": [ "room_night", "food_beverage", "spa", "retail", "parking", "other" ], "type": "string" }, "type": "array" }, "flat_universal_per_incident_limit_at_recovery": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "per_incident_limit_at_recovery": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "per_shift_cumulative_at_recovery": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "policy_kind_at_recovery": { "type": "string" }, "role_code_at_recovery": { "type": "string" } }, "required": [ "policy_kind_at_recovery" ], "title": "Frozen comp authority snapshot", "type": "object" }, "comp_category": { "enum": [ "room_night", "food_beverage", "spa", "retail", "parking", "other" ], "title": "Comp category", "type": "string" }, "failure_category": { "enum": [ "staff_interaction", "room_condition", "fnb_quality", "fnb_service_pace", "billing", "allergy_dietary", "security_safety", "check_in_out", "maintenance", "recognition_failure", "anticipation_miss", "noise", "temperature", "other" ], "title": "Failure category", "type": "string" }, "failure_subject_text": { "title": "What went wrong", "type": "string" }, "follow_up_due_at": { "format": "date-time", "title": "Follow-up due", "type": "string" }, "happened_at": { "format": "date-time", "title": "When the failure happened", "type": "string" }, "interactional_quality": { "enum": [ "failed", "adequate", "genuine", "excellent" ], "title": "How the recovery landed", "type": "string" }, "person_id": { "format": "uuid", "title": "Person who experienced the failure", "type": "string", "x-aerandil-references": "hospitality.person" }, "recovery_action_category": { "enum": [ "apology_only", "apology_plus_gesture", "apology_plus_comp", "apology_plus_upgrade", "complaint_handling_only", "gesture_declined_with_dignity", "escalated_unresolved" ], "title": "Recovery action category", "type": "string" }, "recovery_authoriser": { "title": "Authoriser principal identifier", "type": "string" }, "recovery_process_stages_completed": { "items": { "enum": [ "aware", "acknowledge", "apologise", "act", "additional_generosity" ], "type": "string" }, "title": "USHG 5 As stages completed", "type": "array" }, "severity": { "enum": [ "minor", "moderate", "significant", "severe", "safety_health" ], "title": "Severity", "type": "string" }, "time_to_first_response_seconds": { "title": "Seconds until first response", "type": "integer" }, "time_to_resolution_seconds": { "title": "Seconds until resolved", "type": "integer" } }, "required": [ "person_id", "failure_category", "severity", "failure_subject_text", "recovery_action_category", "recovery_process_stages_completed", "comp_authority_snapshot", "recovery_authoriser", "happened_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.recovery_event_for_person", "hospitality.link.recovery_event_in_venue" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.service_recovery_event" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record service recovery (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_service_recovery/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_service_recovery`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_service_recovery", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "comp_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Comp amount", "type": "object" }, "comp_authority_snapshot": { "properties": { "comp_categories_allowed_at_recovery": { "items": { "enum": [ "room_night", "food_beverage", "spa", "retail", "parking", "other" ], "type": "string" }, "type": "array" }, "flat_universal_per_incident_limit_at_recovery": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "per_incident_limit_at_recovery": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "per_shift_cumulative_at_recovery": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "policy_kind_at_recovery": { "type": "string" }, "role_code_at_recovery": { "type": "string" } }, "required": [ "policy_kind_at_recovery" ], "title": "Frozen comp authority snapshot", "type": "object" }, "comp_category": { "enum": [ "room_night", "food_beverage", "spa", "retail", "parking", "other" ], "title": "Comp category", "type": "string" }, "failure_category": { "enum": [ "staff_interaction", "room_condition", "fnb_quality", "fnb_service_pace", "billing", "allergy_dietary", "security_safety", "check_in_out", "maintenance", "recognition_failure", "anticipation_miss", "noise", "temperature", "other" ], "title": "Failure category", "type": "string" }, "failure_subject_text": { "title": "What went wrong", "type": "string" }, "follow_up_due_at": { "format": "date-time", "title": "Follow-up due", "type": "string" }, "happened_at": { "format": "date-time", "title": "When the failure happened", "type": "string" }, "interactional_quality": { "enum": [ "failed", "adequate", "genuine", "excellent" ], "title": "How the recovery landed", "type": "string" }, "person_id": { "format": "uuid", "title": "Person who experienced the failure", "type": "string", "x-aerandil-references": "hospitality.person" }, "recovery_action_category": { "enum": [ "apology_only", "apology_plus_gesture", "apology_plus_comp", "apology_plus_upgrade", "complaint_handling_only", "gesture_declined_with_dignity", "escalated_unresolved" ], "title": "Recovery action category", "type": "string" }, "recovery_authoriser": { "title": "Authoriser principal identifier", "type": "string" }, "recovery_process_stages_completed": { "items": { "enum": [ "aware", "acknowledge", "apologise", "act", "additional_generosity" ], "type": "string" }, "title": "USHG 5 As stages completed", "type": "array" }, "severity": { "enum": [ "minor", "moderate", "significant", "severe", "safety_health" ], "title": "Severity", "type": "string" }, "time_to_first_response_seconds": { "title": "Seconds until first response", "type": "integer" }, "time_to_resolution_seconds": { "title": "Seconds until resolved", "type": "integer" } }, "required": [ "person_id", "failure_category", "severity", "failure_subject_text", "recovery_action_category", "recovery_process_stages_completed", "comp_authority_snapshot", "recovery_authoriser", "happened_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record service recovery (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_service_recovery/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_service_recovery` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_service_recovery:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_service_recovery", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "comp_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Comp amount", "type": "object" }, "comp_authority_snapshot": { "properties": { "comp_categories_allowed_at_recovery": { "items": { "enum": [ "room_night", "food_beverage", "spa", "retail", "parking", "other" ], "type": "string" }, "type": "array" }, "flat_universal_per_incident_limit_at_recovery": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "per_incident_limit_at_recovery": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "per_shift_cumulative_at_recovery": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "policy_kind_at_recovery": { "type": "string" }, "role_code_at_recovery": { "type": "string" } }, "required": [ "policy_kind_at_recovery" ], "title": "Frozen comp authority snapshot", "type": "object" }, "comp_category": { "enum": [ "room_night", "food_beverage", "spa", "retail", "parking", "other" ], "title": "Comp category", "type": "string" }, "failure_category": { "enum": [ "staff_interaction", "room_condition", "fnb_quality", "fnb_service_pace", "billing", "allergy_dietary", "security_safety", "check_in_out", "maintenance", "recognition_failure", "anticipation_miss", "noise", "temperature", "other" ], "title": "Failure category", "type": "string" }, "failure_subject_text": { "title": "What went wrong", "type": "string" }, "follow_up_due_at": { "format": "date-time", "title": "Follow-up due", "type": "string" }, "happened_at": { "format": "date-time", "title": "When the failure happened", "type": "string" }, "interactional_quality": { "enum": [ "failed", "adequate", "genuine", "excellent" ], "title": "How the recovery landed", "type": "string" }, "person_id": { "format": "uuid", "title": "Person who experienced the failure", "type": "string", "x-aerandil-references": "hospitality.person" }, "recovery_action_category": { "enum": [ "apology_only", "apology_plus_gesture", "apology_plus_comp", "apology_plus_upgrade", "complaint_handling_only", "gesture_declined_with_dignity", "escalated_unresolved" ], "title": "Recovery action category", "type": "string" }, "recovery_authoriser": { "title": "Authoriser principal identifier", "type": "string" }, "recovery_process_stages_completed": { "items": { "enum": [ "aware", "acknowledge", "apologise", "act", "additional_generosity" ], "type": "string" }, "title": "USHG 5 As stages completed", "type": "array" }, "severity": { "enum": [ "minor", "moderate", "significant", "severe", "safety_health" ], "title": "Severity", "type": "string" }, "time_to_first_response_seconds": { "title": "Seconds until first response", "type": "integer" }, "time_to_resolution_seconds": { "title": "Seconds until resolved", "type": "integer" } }, "required": [ "person_id", "failure_category", "severity", "failure_subject_text", "recovery_action_category", "recovery_process_stages_completed", "comp_authority_snapshot", "recovery_authoriser", "happened_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record service recovery (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_staff_certification/apply": { "post": { "description": "Record a credential grant for a staff member. Renewals are a fresh grant, not a mutation; the current credential of a kind is the latest non-revoked, non-expired row.\n\nEffects: create hospitality.staff_certification; link hospitality.link.staff_certification_for_staff.", "operationId": "apply_hospitality_action_record_staff_certification", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "credential_reference": { "title": "Certificate / badge number", "type": "string" }, "expiry_date": { "format": "date", "title": "Expiry date (null = non-expiring)", "type": "string" }, "issue_date": { "format": "date", "title": "Issue date", "type": "string" }, "issuing_authority": { "title": "Issuing authority (e.g. ServSafe, WSET)", "type": "string" }, "kind": { "enum": [ "food_safety_manager", "food_safety_handler", "allergen_awareness", "alcohol_service", "haccp", "sommelier", "wset", "first_aid", "cpr", "pool_lifeguard", "massage_therapy_license", "cosmetology_license", "fire_safety", "other" ], "title": "Certification kind", "type": "string" }, "verification_status": { "enum": [ "self_reported", "document_on_file", "verified" ], "title": "Verification status (default self_reported)", "type": "string" } }, "required": [ "kind", "issue_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.staff_certification_for_staff" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.staff_certification" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_staff_certification:apply" ] } ], "summary": "Record staff certification", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.record_staff_certification/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_staff_certification` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_staff_certification:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_staff_certification", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "credential_reference": { "title": "Certificate / badge number", "type": "string" }, "expiry_date": { "format": "date", "title": "Expiry date (null = non-expiring)", "type": "string" }, "issue_date": { "format": "date", "title": "Issue date", "type": "string" }, "issuing_authority": { "title": "Issuing authority (e.g. ServSafe, WSET)", "type": "string" }, "kind": { "enum": [ "food_safety_manager", "food_safety_handler", "allergen_awareness", "alcohol_service", "haccp", "sommelier", "wset", "first_aid", "cpr", "pool_lifeguard", "massage_therapy_license", "cosmetology_license", "fire_safety", "other" ], "title": "Certification kind", "type": "string" }, "verification_status": { "enum": [ "self_reported", "document_on_file", "verified" ], "title": "Verification status (default self_reported)", "type": "string" } }, "required": [ "kind", "issue_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.staff_certification_for_staff" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.staff_certification" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record staff certification (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.record_staff_certification/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_staff_certification`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_staff_certification", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "credential_reference": { "title": "Certificate / badge number", "type": "string" }, "expiry_date": { "format": "date", "title": "Expiry date (null = non-expiring)", "type": "string" }, "issue_date": { "format": "date", "title": "Issue date", "type": "string" }, "issuing_authority": { "title": "Issuing authority (e.g. ServSafe, WSET)", "type": "string" }, "kind": { "enum": [ "food_safety_manager", "food_safety_handler", "allergen_awareness", "alcohol_service", "haccp", "sommelier", "wset", "first_aid", "cpr", "pool_lifeguard", "massage_therapy_license", "cosmetology_license", "fire_safety", "other" ], "title": "Certification kind", "type": "string" }, "verification_status": { "enum": [ "self_reported", "document_on_file", "verified" ], "title": "Verification status (default self_reported)", "type": "string" } }, "required": [ "kind", "issue_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record staff certification (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.record_staff_certification/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_staff_certification` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_staff_certification:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_staff_certification", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "credential_reference": { "title": "Certificate / badge number", "type": "string" }, "expiry_date": { "format": "date", "title": "Expiry date (null = non-expiring)", "type": "string" }, "issue_date": { "format": "date", "title": "Issue date", "type": "string" }, "issuing_authority": { "title": "Issuing authority (e.g. ServSafe, WSET)", "type": "string" }, "kind": { "enum": [ "food_safety_manager", "food_safety_handler", "allergen_awareness", "alcohol_service", "haccp", "sommelier", "wset", "first_aid", "cpr", "pool_lifeguard", "massage_therapy_license", "cosmetology_license", "fire_safety", "other" ], "title": "Certification kind", "type": "string" }, "verification_status": { "enum": [ "self_reported", "document_on_file", "verified" ], "title": "Verification status (default self_reported)", "type": "string" } }, "required": [ "kind", "issue_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record staff certification (rollup delta)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.record_turnaway/apply": { "post": { "description": "Record a request for rooms the house refused — the lost-demand record a forecast needs beside its sales. Carries the night and stay asked for, when the guest asked (`requested_at`, business time, defaults to now), why the desk said no, the minimum stay in force if one was, and the segment, channel, room type and guest when known. A guest who declined the rate (`rate`, a regret) carries the plan and the nightly rate quoted — the look that did not book — and a request through the booking engine carries the engine's key for the browser that asked (`visitor_id`), which `create_reservation` takes too. Holds no inventory. Replay-safe via `external_ref` (the turnaway business key): a repeat with the same ref lands on the existing record and writes nothing.\n\nEffects: create hospitality.turnaway; link hospitality.link.turnaway_for_property; link hospitality.link.turnaway_for_room_type; link hospitality.link.turnaway_for_guest; link hospitality.link.turnaway_for_rate_plan.", "operationId": "apply_hospitality_action_record_turnaway", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults": { "title": "Adults asked for", "type": "integer" }, "arrival_date": { "format": "date", "title": "The arrival night asked for", "type": "string" }, "external_ref": { "title": "Replay key from the recording source", "type": "string" }, "guest_id": { "format": "uuid", "title": "Who asked, when known", "type": "string", "x-aerandil-references": "hospitality.person" }, "market_segment": { "enum": [ "transient", "group", "contract" ], "title": "Market segment of the demand, when the desk could tell", "type": "string" }, "min_stay_in_force": { "title": "The minimum stay posted for the arrival at the time", "type": "integer" }, "nights": { "title": "Nights asked for", "type": "integer" }, "notes": { "title": "What the desk noted", "type": "string" }, "property_id": { "format": "uuid", "title": "The house that refused the request", "type": "string", "x-aerandil-references": "hospitality.property" }, "quoted_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Rate quoted", "type": "object" }, "rate_plan_id": { "format": "uuid", "title": "The plan the guest was quoted on, when a rate was offered", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "reason": { "enum": [ "sold_out", "min_stay", "closed", "rate", "other" ], "title": "Why the request was refused", "type": "string" }, "requested_at": { "format": "date-time", "title": "When the guest asked (defaults to now; must not be in the future)", "type": "string" }, "room_type_id": { "format": "uuid", "title": "Room type asked for, when one was", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "Channel the request arrived through, when known", "type": "string" }, "visitor_id": { "title": "The booking engine's key for the browser that asked, when its tag read one", "type": "string" } }, "required": [ "property_id", "arrival_date", "nights", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.turnaway_for_property", "hospitality.link.turnaway_for_room_type", "hospitality.link.turnaway_for_guest", "hospitality.link.turnaway_for_rate_plan" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.turnaway" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_turnaway:apply" ] } ], "summary": "Record turnaway", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.record_turnaway/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_turnaway` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_turnaway:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_turnaway", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults": { "title": "Adults asked for", "type": "integer" }, "arrival_date": { "format": "date", "title": "The arrival night asked for", "type": "string" }, "external_ref": { "title": "Replay key from the recording source", "type": "string" }, "guest_id": { "format": "uuid", "title": "Who asked, when known", "type": "string", "x-aerandil-references": "hospitality.person" }, "market_segment": { "enum": [ "transient", "group", "contract" ], "title": "Market segment of the demand, when the desk could tell", "type": "string" }, "min_stay_in_force": { "title": "The minimum stay posted for the arrival at the time", "type": "integer" }, "nights": { "title": "Nights asked for", "type": "integer" }, "notes": { "title": "What the desk noted", "type": "string" }, "property_id": { "format": "uuid", "title": "The house that refused the request", "type": "string", "x-aerandil-references": "hospitality.property" }, "quoted_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Rate quoted", "type": "object" }, "rate_plan_id": { "format": "uuid", "title": "The plan the guest was quoted on, when a rate was offered", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "reason": { "enum": [ "sold_out", "min_stay", "closed", "rate", "other" ], "title": "Why the request was refused", "type": "string" }, "requested_at": { "format": "date-time", "title": "When the guest asked (defaults to now; must not be in the future)", "type": "string" }, "room_type_id": { "format": "uuid", "title": "Room type asked for, when one was", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "Channel the request arrived through, when known", "type": "string" }, "visitor_id": { "title": "The booking engine's key for the browser that asked, when its tag read one", "type": "string" } }, "required": [ "property_id", "arrival_date", "nights", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.turnaway_for_property", "hospitality.link.turnaway_for_room_type", "hospitality.link.turnaway_for_guest", "hospitality.link.turnaway_for_rate_plan" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.turnaway" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record turnaway (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.record_turnaway/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_turnaway`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_turnaway", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults": { "title": "Adults asked for", "type": "integer" }, "arrival_date": { "format": "date", "title": "The arrival night asked for", "type": "string" }, "external_ref": { "title": "Replay key from the recording source", "type": "string" }, "guest_id": { "format": "uuid", "title": "Who asked, when known", "type": "string", "x-aerandil-references": "hospitality.person" }, "market_segment": { "enum": [ "transient", "group", "contract" ], "title": "Market segment of the demand, when the desk could tell", "type": "string" }, "min_stay_in_force": { "title": "The minimum stay posted for the arrival at the time", "type": "integer" }, "nights": { "title": "Nights asked for", "type": "integer" }, "notes": { "title": "What the desk noted", "type": "string" }, "property_id": { "format": "uuid", "title": "The house that refused the request", "type": "string", "x-aerandil-references": "hospitality.property" }, "quoted_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Rate quoted", "type": "object" }, "rate_plan_id": { "format": "uuid", "title": "The plan the guest was quoted on, when a rate was offered", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "reason": { "enum": [ "sold_out", "min_stay", "closed", "rate", "other" ], "title": "Why the request was refused", "type": "string" }, "requested_at": { "format": "date-time", "title": "When the guest asked (defaults to now; must not be in the future)", "type": "string" }, "room_type_id": { "format": "uuid", "title": "Room type asked for, when one was", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "Channel the request arrived through, when known", "type": "string" }, "visitor_id": { "title": "The booking engine's key for the browser that asked, when its tag read one", "type": "string" } }, "required": [ "property_id", "arrival_date", "nights", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record turnaway (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.record_turnaway/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_turnaway` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_turnaway:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_turnaway", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults": { "title": "Adults asked for", "type": "integer" }, "arrival_date": { "format": "date", "title": "The arrival night asked for", "type": "string" }, "external_ref": { "title": "Replay key from the recording source", "type": "string" }, "guest_id": { "format": "uuid", "title": "Who asked, when known", "type": "string", "x-aerandil-references": "hospitality.person" }, "market_segment": { "enum": [ "transient", "group", "contract" ], "title": "Market segment of the demand, when the desk could tell", "type": "string" }, "min_stay_in_force": { "title": "The minimum stay posted for the arrival at the time", "type": "integer" }, "nights": { "title": "Nights asked for", "type": "integer" }, "notes": { "title": "What the desk noted", "type": "string" }, "property_id": { "format": "uuid", "title": "The house that refused the request", "type": "string", "x-aerandil-references": "hospitality.property" }, "quoted_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Rate quoted", "type": "object" }, "rate_plan_id": { "format": "uuid", "title": "The plan the guest was quoted on, when a rate was offered", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "reason": { "enum": [ "sold_out", "min_stay", "closed", "rate", "other" ], "title": "Why the request was refused", "type": "string" }, "requested_at": { "format": "date-time", "title": "When the guest asked (defaults to now; must not be in the future)", "type": "string" }, "room_type_id": { "format": "uuid", "title": "Room type asked for, when one was", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "Channel the request arrived through, when known", "type": "string" }, "visitor_id": { "title": "The booking engine's key for the browser that asked, when its tag read one", "type": "string" } }, "required": [ "property_id", "arrival_date", "nights", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record turnaway (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.record_utility_cost/apply": { "post": { "description": "Post one utility invoice line (USALI 12 Schedule 9 — Energy, Water, and Waste), with the metered consumption when the invoice carries it. `category` is stamped from `kind`; the quantity/unit pair stays in its source unit. `external_ref` is the idempotency anchor for invoice imports. Emits `utility.cost.recorded` for the `daily_eww` projection.\n\nEffects: create hospitality.utility_ledger_entry; link hospitality.link.utility_entry_at_property.", "operationId": "apply_hospitality_action_record_utility_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "business_date": { "format": "date", "title": "Accrual business date", "type": "string" }, "consumption_quantity": { "format": "decimal", "title": "Metered consumption quantity (requires consumption_unit)", "type": "string" }, "consumption_unit": { "enum": [ "kwh", "mwh", "therm", "mmbtu", "gallon", "cubic_meter", "litre", "kilogram", "pound", "ton", "tonne", "cubic_yard", "other" ], "title": "Consumption unit (requires consumption_quantity)", "type": "string" }, "external_ref": { "title": "Invoice-line id (idempotency anchor)", "type": "string" }, "kind": { "enum": [ "electricity", "natural_gas", "fuel_oil", "propane", "steam", "chilled_water", "renewable_electricity", "water", "sewer", "waste_landfill", "waste_recycling", "waste_organics", "waste_hazardous", "contract_services", "other" ], "title": "USALI Schedule 9 account", "type": "string" }, "period_end": { "format": "date", "title": "Billing-period end (optional)", "type": "string" }, "period_start": { "format": "date", "title": "Billing-period start (optional)", "type": "string" }, "source": { "enum": [ "invoice_import", "manual" ], "title": "Provenance (defaults to `invoice_import`)", "type": "string" } }, "required": [ "kind", "amount", "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.utility_entry_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.utility_ledger_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_utility_cost:apply" ] } ], "summary": "Record utility cost", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_utility_cost/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_utility_cost` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_utility_cost:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_utility_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "business_date": { "format": "date", "title": "Accrual business date", "type": "string" }, "consumption_quantity": { "format": "decimal", "title": "Metered consumption quantity (requires consumption_unit)", "type": "string" }, "consumption_unit": { "enum": [ "kwh", "mwh", "therm", "mmbtu", "gallon", "cubic_meter", "litre", "kilogram", "pound", "ton", "tonne", "cubic_yard", "other" ], "title": "Consumption unit (requires consumption_quantity)", "type": "string" }, "external_ref": { "title": "Invoice-line id (idempotency anchor)", "type": "string" }, "kind": { "enum": [ "electricity", "natural_gas", "fuel_oil", "propane", "steam", "chilled_water", "renewable_electricity", "water", "sewer", "waste_landfill", "waste_recycling", "waste_organics", "waste_hazardous", "contract_services", "other" ], "title": "USALI Schedule 9 account", "type": "string" }, "period_end": { "format": "date", "title": "Billing-period end (optional)", "type": "string" }, "period_start": { "format": "date", "title": "Billing-period start (optional)", "type": "string" }, "source": { "enum": [ "invoice_import", "manual" ], "title": "Provenance (defaults to `invoice_import`)", "type": "string" } }, "required": [ "kind", "amount", "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.utility_entry_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.utility_ledger_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record utility cost (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_utility_cost/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_utility_cost`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_utility_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "business_date": { "format": "date", "title": "Accrual business date", "type": "string" }, "consumption_quantity": { "format": "decimal", "title": "Metered consumption quantity (requires consumption_unit)", "type": "string" }, "consumption_unit": { "enum": [ "kwh", "mwh", "therm", "mmbtu", "gallon", "cubic_meter", "litre", "kilogram", "pound", "ton", "tonne", "cubic_yard", "other" ], "title": "Consumption unit (requires consumption_quantity)", "type": "string" }, "external_ref": { "title": "Invoice-line id (idempotency anchor)", "type": "string" }, "kind": { "enum": [ "electricity", "natural_gas", "fuel_oil", "propane", "steam", "chilled_water", "renewable_electricity", "water", "sewer", "waste_landfill", "waste_recycling", "waste_organics", "waste_hazardous", "contract_services", "other" ], "title": "USALI Schedule 9 account", "type": "string" }, "period_end": { "format": "date", "title": "Billing-period end (optional)", "type": "string" }, "period_start": { "format": "date", "title": "Billing-period start (optional)", "type": "string" }, "source": { "enum": [ "invoice_import", "manual" ], "title": "Provenance (defaults to `invoice_import`)", "type": "string" } }, "required": [ "kind", "amount", "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record utility cost (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_utility_cost/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_utility_cost` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_utility_cost:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_utility_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount", "type": "object" }, "business_date": { "format": "date", "title": "Accrual business date", "type": "string" }, "consumption_quantity": { "format": "decimal", "title": "Metered consumption quantity (requires consumption_unit)", "type": "string" }, "consumption_unit": { "enum": [ "kwh", "mwh", "therm", "mmbtu", "gallon", "cubic_meter", "litre", "kilogram", "pound", "ton", "tonne", "cubic_yard", "other" ], "title": "Consumption unit (requires consumption_quantity)", "type": "string" }, "external_ref": { "title": "Invoice-line id (idempotency anchor)", "type": "string" }, "kind": { "enum": [ "electricity", "natural_gas", "fuel_oil", "propane", "steam", "chilled_water", "renewable_electricity", "water", "sewer", "waste_landfill", "waste_recycling", "waste_organics", "waste_hazardous", "contract_services", "other" ], "title": "USALI Schedule 9 account", "type": "string" }, "period_end": { "format": "date", "title": "Billing-period end (optional)", "type": "string" }, "period_start": { "format": "date", "title": "Billing-period start (optional)", "type": "string" }, "source": { "enum": [ "invoice_import", "manual" ], "title": "Provenance (defaults to `invoice_import`)", "type": "string" } }, "required": [ "kind", "amount", "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record utility cost (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_venue_visit/apply": { "post": { "description": "Log a non-reservation visit to the target venue by a person — the bar host's book turning into structured data. Independent of recognition: a visit may pass without a typed gesture, in which case no recognition event is recorded. The companion `recognise_person` action handles recognition-tier ladder transitions, with `record_recognition_event` from proposal 0003 handling the typed gesture itself.\n\nEffects: create hospitality.venue_visit; link hospitality.link.venue_visit_for_person; link hospitality.link.venue_visit_at_venue.", "operationId": "apply_hospitality_action_record_venue_visit", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "arrived_at": { "format": "date-time", "title": "Arrived at", "type": "string" }, "covers_count": { "title": "Covers count", "type": "integer" }, "departed_at": { "format": "date-time", "title": "Departed at", "type": "string" }, "host_recogniser": { "title": "Host / maître d' / bartender principal identifier", "type": "string" }, "host_stand_notes": { "title": "Host stand notes", "type": "string" }, "observed_companions_text": { "title": "Observed companions", "type": "string" }, "party_size": { "title": "Party size", "type": "integer" }, "person_id": { "format": "uuid", "title": "Person visiting", "type": "string", "x-aerandil-references": "hospitality.person" }, "seated_at_text": { "title": "Seating location", "type": "string" }, "visited_on": { "format": "date", "title": "Visit date (venue local timezone)", "type": "string" } }, "required": [ "person_id", "visited_on", "host_recogniser" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.venue_visit_for_person", "hospitality.link.venue_visit_at_venue" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.venue_visit" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_venue_visit:apply" ] } ], "summary": "Record venue visit", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_venue_visit/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_venue_visit` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_venue_visit:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_venue_visit", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "arrived_at": { "format": "date-time", "title": "Arrived at", "type": "string" }, "covers_count": { "title": "Covers count", "type": "integer" }, "departed_at": { "format": "date-time", "title": "Departed at", "type": "string" }, "host_recogniser": { "title": "Host / maître d' / bartender principal identifier", "type": "string" }, "host_stand_notes": { "title": "Host stand notes", "type": "string" }, "observed_companions_text": { "title": "Observed companions", "type": "string" }, "party_size": { "title": "Party size", "type": "integer" }, "person_id": { "format": "uuid", "title": "Person visiting", "type": "string", "x-aerandil-references": "hospitality.person" }, "seated_at_text": { "title": "Seating location", "type": "string" }, "visited_on": { "format": "date", "title": "Visit date (venue local timezone)", "type": "string" } }, "required": [ "person_id", "visited_on", "host_recogniser" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.venue_visit_for_person", "hospitality.link.venue_visit_at_venue" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.venue_visit" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record venue visit (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_venue_visit/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_venue_visit`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_venue_visit", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "arrived_at": { "format": "date-time", "title": "Arrived at", "type": "string" }, "covers_count": { "title": "Covers count", "type": "integer" }, "departed_at": { "format": "date-time", "title": "Departed at", "type": "string" }, "host_recogniser": { "title": "Host / maître d' / bartender principal identifier", "type": "string" }, "host_stand_notes": { "title": "Host stand notes", "type": "string" }, "observed_companions_text": { "title": "Observed companions", "type": "string" }, "party_size": { "title": "Party size", "type": "integer" }, "person_id": { "format": "uuid", "title": "Person visiting", "type": "string", "x-aerandil-references": "hospitality.person" }, "seated_at_text": { "title": "Seating location", "type": "string" }, "visited_on": { "format": "date", "title": "Visit date (venue local timezone)", "type": "string" } }, "required": [ "person_id", "visited_on", "host_recogniser" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record venue visit (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_venue_visit/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_venue_visit` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_venue_visit:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_venue_visit", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "arrived_at": { "format": "date-time", "title": "Arrived at", "type": "string" }, "covers_count": { "title": "Covers count", "type": "integer" }, "departed_at": { "format": "date-time", "title": "Departed at", "type": "string" }, "host_recogniser": { "title": "Host / maître d' / bartender principal identifier", "type": "string" }, "host_stand_notes": { "title": "Host stand notes", "type": "string" }, "observed_companions_text": { "title": "Observed companions", "type": "string" }, "party_size": { "title": "Party size", "type": "integer" }, "person_id": { "format": "uuid", "title": "Person visiting", "type": "string", "x-aerandil-references": "hospitality.person" }, "seated_at_text": { "title": "Seating location", "type": "string" }, "visited_on": { "format": "date", "title": "Visit date (venue local timezone)", "type": "string" } }, "required": [ "person_id", "visited_on", "host_recogniser" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record venue visit (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.record_work_order_entry/apply": { "post": { "description": "Add a line to a work order's thread: a `note`, `work` (with minutes_spent), `material` (with the parts used), or a `delegation` (with the role the order is handed to). Any line may also carry time and parts. The author is the staff member behind the principal when there is one (a handset session), linked through `work_order_entry_recorded_by`; `recorded_by` names the principal either way. A delegation also stamps the role on the order (`delegated_to_role`, the board's delegated filter) until complete_work_order or void_work_order clears it; one to the role the order already stands with writes the line and moves nothing (its event says `role_changed: false`, so nobody is nudged, 2026-10-17). Refused on a voided order; a completed order takes notes only. Postponement and resolution lines are written by postpone_work_order and complete_work_order, never here. Replay-safe under the apply route's Idempotency-Key — the handset's offline queue sends one per line. A part naming a catalogued `material_id` (2026-10-14) is consumed from its `store_id` — or the house's default workshop — in the same transaction (a `consumption` movement on the order, `stock_movement_for_work_order`), refused when it would take the store below zero unless the store allows it; its description defaults to the material's name and its unit is the material's. A free-text part moves no stock. The part comes out of the acting role's own stores, as on every stock verb (2026-10-17): an engineer's session from a workshop, a housekeeping supervisor's from any store but one — the default workshop included — else the line is refused (403).\n\nEffects: create hospitality.work_order_entry; link hospitality.link.work_order_entry_for_work_order; link hospitality.link.work_order_entry_recorded_by; modify hospitality.work_order; create hospitality.stock_movement; create hospitality.stock_level; modify hospitality.stock_level; link hospitality.link.stock_movement_for_level; link hospitality.link.stock_level_for_material; link hospitality.link.stock_level_in_store; link hospitality.link.stock_movement_recorded_by; link hospitality.link.stock_movement_for_work_order.", "operationId": "apply_hospitality_action_record_work_order_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "delegated_to_role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "The role the order is handed to (required for a delegation)", "type": "string" }, "kind": { "enum": [ "note", "work", "material", "delegation" ], "title": "note, work, material, or delegation", "type": "string" }, "materials": { "items": { "properties": { "description": { "type": "string" }, "material_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "type": "string" }, "store_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.stock_store" }, "unit": { "type": "string" } }, "required": [ "quantity" ], "type": "object" }, "title": "Materials", "type": "array" }, "minutes_spent": { "title": "Time spent, in minutes (required for a work line; 0 to 10080)", "type": "integer" }, "recorded_at": { "format": "date-time", "title": "When the line was written (defaults to now; a handset queueing offline sends its own time; refused when more than five minutes ahead of the kernel's clock)", "type": "string" }, "text": { "title": "The words on the line (required for a note)", "type": "string" } }, "required": [ "kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.work_order_entry_for_work_order", "hospitality.link.work_order_entry_recorded_by", "hospitality.link.stock_movement_for_level", "hospitality.link.stock_level_for_material", "hospitality.link.stock_level_in_store", "hospitality.link.stock_movement_recorded_by", "hospitality.link.stock_movement_for_work_order" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.work_order_entry", "hospitality.work_order", "hospitality.stock_movement", "hospitality.stock_level" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_work_order_entry:apply" ] } ], "summary": "Record work order entry", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.record_work_order_entry/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_record_work_order_entry` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.record_work_order_entry:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_record_work_order_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "delegated_to_role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "The role the order is handed to (required for a delegation)", "type": "string" }, "kind": { "enum": [ "note", "work", "material", "delegation" ], "title": "note, work, material, or delegation", "type": "string" }, "materials": { "items": { "properties": { "description": { "type": "string" }, "material_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "type": "string" }, "store_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.stock_store" }, "unit": { "type": "string" } }, "required": [ "quantity" ], "type": "object" }, "title": "Materials", "type": "array" }, "minutes_spent": { "title": "Time spent, in minutes (required for a work line; 0 to 10080)", "type": "integer" }, "recorded_at": { "format": "date-time", "title": "When the line was written (defaults to now; a handset queueing offline sends its own time; refused when more than five minutes ahead of the kernel's clock)", "type": "string" }, "text": { "title": "The words on the line (required for a note)", "type": "string" } }, "required": [ "kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.work_order_entry_for_work_order", "hospitality.link.work_order_entry_recorded_by", "hospitality.link.stock_movement_for_level", "hospitality.link.stock_level_for_material", "hospitality.link.stock_level_in_store", "hospitality.link.stock_movement_recorded_by", "hospitality.link.stock_movement_for_work_order" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.work_order_entry", "hospitality.work_order", "hospitality.stock_movement", "hospitality.stock_level" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Record work order entry (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.record_work_order_entry/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_record_work_order_entry`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_record_work_order_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "delegated_to_role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "The role the order is handed to (required for a delegation)", "type": "string" }, "kind": { "enum": [ "note", "work", "material", "delegation" ], "title": "note, work, material, or delegation", "type": "string" }, "materials": { "items": { "properties": { "description": { "type": "string" }, "material_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "type": "string" }, "store_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.stock_store" }, "unit": { "type": "string" } }, "required": [ "quantity" ], "type": "object" }, "title": "Materials", "type": "array" }, "minutes_spent": { "title": "Time spent, in minutes (required for a work line; 0 to 10080)", "type": "integer" }, "recorded_at": { "format": "date-time", "title": "When the line was written (defaults to now; a handset queueing offline sends its own time; refused when more than five minutes ahead of the kernel's clock)", "type": "string" }, "text": { "title": "The words on the line (required for a note)", "type": "string" } }, "required": [ "kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Record work order entry (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.record_work_order_entry/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_record_work_order_entry` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.record_work_order_entry:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_record_work_order_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "delegated_to_role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "The role the order is handed to (required for a delegation)", "type": "string" }, "kind": { "enum": [ "note", "work", "material", "delegation" ], "title": "note, work, material, or delegation", "type": "string" }, "materials": { "items": { "properties": { "description": { "type": "string" }, "material_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "type": "string" }, "store_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.stock_store" }, "unit": { "type": "string" } }, "required": [ "quantity" ], "type": "object" }, "title": "Materials", "type": "array" }, "minutes_spent": { "title": "Time spent, in minutes (required for a work line; 0 to 10080)", "type": "integer" }, "recorded_at": { "format": "date-time", "title": "When the line was written (defaults to now; a handset queueing offline sends its own time; refused when more than five minutes ahead of the kernel's clock)", "type": "string" }, "text": { "title": "The words on the line (required for a note)", "type": "string" } }, "required": [ "kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Record work order entry (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.recount_stock_level/apply": { "post": { "description": "Check a stock level's cached on_hand against its movements — the sum of their quantities, the truth the cache keeps — and write the sum back when they disagree, emitting `stock_level.reconciled` with the previous figure, the derived one and the difference. A level that agrees is left alone and nothing is said. The folio balance's reconcile, for stock (2026-10-04): the cache is checked, never trusted.\n\nEffects: modify hospitality.stock_level.", "operationId": "apply_hospitality_action_recount_stock_level", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_level" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.stock_level" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.recount_stock_level:apply" ] } ], "summary": "Recount stock level", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.recount_stock_level/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_recount_stock_level` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.recount_stock_level:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_recount_stock_level", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_level" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.stock_level" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Recount stock level (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.recount_stock_level/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_recount_stock_level`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_recount_stock_level", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_level" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Recount stock level (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.recount_stock_level/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_recount_stock_level` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.recount_stock_level:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_recount_stock_level", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_level" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Recount stock level (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.redact_person_recognition/apply": { "post": { "description": "GDPR right-to-erasure surface for recognition data. Zeroes out `mobility_considerations` and free-text recognition fields; leaves projection and financial-audit fields intact per Article 17(3) retention-required-records carve-out.\n\nEffects: modify hospitality.person.", "operationId": "apply_hospitality_action_redact_person_recognition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.person" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.redact_person_recognition:apply" ] } ], "summary": "Redact person recognition", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.redact_person_recognition/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_redact_person_recognition` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.redact_person_recognition:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_redact_person_recognition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.person" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Redact person recognition (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.redact_person_recognition/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_redact_person_recognition`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_redact_person_recognition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Redact person recognition (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.redact_person_recognition/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_redact_person_recognition` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.redact_person_recognition:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_redact_person_recognition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Redact person recognition (rollup delta)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.refresh_folio_aging/apply": { "post": { "description": "Recompute `ar_aging_bucket` from `due_at` and payment history. Idempotent.\n\nEffects: modify hospitality.folio.", "operationId": "apply_hospitality_action_refresh_folio_aging", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.refresh_folio_aging:apply" ] } ], "summary": "Refresh folio aging", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.refresh_folio_aging/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_refresh_folio_aging` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.refresh_folio_aging:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_refresh_folio_aging", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Refresh folio aging (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.refresh_folio_aging/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_refresh_folio_aging`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_refresh_folio_aging", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Refresh folio aging (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.refresh_folio_aging/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_refresh_folio_aging` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.refresh_folio_aging:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_refresh_folio_aging", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Refresh folio aging (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.refresh_person_projections/apply": { "post": { "description": "Recompute the denormalised projection fields on `person` (`lifetime_value`, `total_stays`, `direct_stays`, `last_stay_date`) and their `*_computed_at` companions from the underlying event history; `direct_repeat_rate` derives from the stored pair at read time. Operator-side rescue hatch; not the primary refresh path.\n\nEffects: modify hospitality.person.", "operationId": "apply_hospitality_action_refresh_person_projections", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.person" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.refresh_person_projections:apply" ] } ], "summary": "Refresh person projections", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.refresh_person_projections/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_refresh_person_projections` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.refresh_person_projections:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_refresh_person_projections", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.person" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Refresh person projections (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.refresh_person_projections/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_refresh_person_projections`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_refresh_person_projections", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Refresh person projections (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.refresh_person_projections/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_refresh_person_projections` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.refresh_person_projections:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_refresh_person_projections", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Refresh person projections (rollup delta)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.refresh_recipe_pour_cost/apply": { "post": { "description": "Recompute the recipe's `pour_cost` by walking its ingredients and sub-recipes against the active `ingredient_supplier_price` row for the recipe's property. Idempotent; updates `pour_cost_computed_at`.\n\nEffects: modify hospitality.recipe.", "operationId": "apply_hospitality_action_refresh_recipe_pour_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.recipe" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.recipe" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.refresh_recipe_pour_cost:apply" ] } ], "summary": "Refresh recipe pour cost", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.refresh_recipe_pour_cost/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_refresh_recipe_pour_cost` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.refresh_recipe_pour_cost:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_refresh_recipe_pour_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.recipe" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.recipe" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Refresh recipe pour cost (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.refresh_recipe_pour_cost/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_refresh_recipe_pour_cost`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_refresh_recipe_pour_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.recipe" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Refresh recipe pour cost (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.refresh_recipe_pour_cost/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_refresh_recipe_pour_cost` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.refresh_recipe_pour_cost:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_refresh_recipe_pour_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.recipe" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Refresh recipe pour cost (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.refresh_staff_projections/apply": { "post": { "description": "Recompute `tenure_years_at_current_property`, `tenure_years_lifetime`, and `comp_authority_summary` from `staff_employment_period` rows + active `comp_authority_policy` rows.\n\nEffects: modify hospitality.staff_member.", "operationId": "apply_hospitality_action_refresh_staff_projections", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.staff_member" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.refresh_staff_projections:apply" ] } ], "summary": "Refresh staff projections", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.refresh_staff_projections/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_refresh_staff_projections` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.refresh_staff_projections:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_refresh_staff_projections", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.staff_member" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Refresh staff projections (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.refresh_staff_projections/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_refresh_staff_projections`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_refresh_staff_projections", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Refresh staff projections (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.refresh_staff_projections/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_refresh_staff_projections` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.refresh_staff_projections:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_refresh_staff_projections", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Refresh staff projections (rollup delta)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.refund_payment/apply": { "post": { "description": "Record a refund request as a negative-amount Payment leg linked to the original settled payment via `payment_refunds_payment`. Validators reject: target not settled, target already a refund leg, target not linked to one folio, refund_amount non-positive, currency mismatch, concurrent pending refund leg, remaining refundable balance exceeded, missing reason, reason = other without note, missing correlation id. Atomically inserts a refund Payment (payment_kind = refund, amount = -refund_amount, method copied from the original, status = pending unless refund_initial_status = refunded for synchronous PSP-confirmed refunds), writes folio_has_payment and payment_refunds_payment links, and (for refunded initial status) sets refund_resolved_at = received_at. v1 admits partial and multiple-partial refunds against the same original payment; unreferenced refunds / stand-alone credits are deferred per proposal 0019 §1 and §10.5. Money leaves the house, so agent principals cannot apply it directly: an agent stages it via `propose_action` and a human confirms (agent_confirm_required).\n\nEffects: create hospitality.payment; link hospitality.link.folio_has_payment; link hospitality.link.payment_refunds_payment; link hospitality.link.payment_for_reservation; modify hospitality.folio; modify hospitality.reservation.\n\nStep-up: a person (a `User` principal) needs a fresh desk step-up proof — A refund sends money back out of the house — or the call is refused `403 step_up_required` before anything runs. Re-enter the passcode at `POST /v1/desk/sessions/{id}/passcode` and retry. Machine principals are not gated.", "operationId": "apply_hospitality_action_refund_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "psp_refund_reference": { "title": "PSP-issued refund reference (Stripe refund.id / Adyen refund pspReference / Checkout.com action_id / Worldpay refund event ref / Braintree refund transaction id / Cybersource credit id / Mews RefundId)", "type": "string" }, "refund_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Refund amount (positive; defaults to remaining refundable balance if unset)", "type": "object" }, "refund_correlation_id": { "title": "Host-side idempotency / reconciliation key (required because two legitimate same-amount partial refunds with the same reason can occur against one payment)", "type": "string" }, "refund_initial_status": { "enum": [ "pending", "refunded" ], "title": "Initial refund leg status: `pending` (PSP accepted but not yet confirmed; defaults to pending) or `refunded` (PSP confirmed synchronously / importing historical confirmed refund)", "type": "string" }, "refund_note": { "title": "Free-form colour, max 1024 chars (required when refund_reason = other)", "type": "string" }, "refund_reason": { "enum": [ "duplicate", "fraudulent", "requested_by_customer", "reservation_cancelled", "deposit_return", "service_recovery", "overcharge_correction", "no_show_policy_exception", "package_component_refund", "membership_cancellation", "chargeback_prevention", "other" ], "title": "Closed REFUND_REASONS taxonomy", "type": "string" }, "refund_requested_at": { "format": "date-time", "title": "Timestamp when the refund was requested / PSP accepted the request (defaults to now)", "type": "string" }, "refund_trace_reference": { "title": "Network trace reference for cardholder-side traceability (often unavailable at request time, populated by resolve_payment_refund)", "type": "string" }, "refund_trace_reference_type": { "enum": [ "arn", "stan", "rrn", "psp_generated", "unavailable" ], "title": "Type tag on refund_trace_reference", "type": "string" } }, "required": [ "refund_reason", "refund_correlation_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_payment", "hospitality.link.payment_refunds_payment", "hospitality.link.payment_for_reservation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.payment", "hospitality.folio", "hospitality.reservation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "403": { "description": "`step_up_required` — a person applied this without a fresh desk step-up proof; nothing ran." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.refund_payment:apply" ] } ], "summary": "Refund payment", "tags": [ "finance" ], "x-aerandil-step-up": { "reason": "A refund sends money back out of the house" } } }, "/v1/actions/hospitality.action.refund_payment/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_refund_payment` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.refund_payment:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_refund_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "psp_refund_reference": { "title": "PSP-issued refund reference (Stripe refund.id / Adyen refund pspReference / Checkout.com action_id / Worldpay refund event ref / Braintree refund transaction id / Cybersource credit id / Mews RefundId)", "type": "string" }, "refund_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Refund amount (positive; defaults to remaining refundable balance if unset)", "type": "object" }, "refund_correlation_id": { "title": "Host-side idempotency / reconciliation key (required because two legitimate same-amount partial refunds with the same reason can occur against one payment)", "type": "string" }, "refund_initial_status": { "enum": [ "pending", "refunded" ], "title": "Initial refund leg status: `pending` (PSP accepted but not yet confirmed; defaults to pending) or `refunded` (PSP confirmed synchronously / importing historical confirmed refund)", "type": "string" }, "refund_note": { "title": "Free-form colour, max 1024 chars (required when refund_reason = other)", "type": "string" }, "refund_reason": { "enum": [ "duplicate", "fraudulent", "requested_by_customer", "reservation_cancelled", "deposit_return", "service_recovery", "overcharge_correction", "no_show_policy_exception", "package_component_refund", "membership_cancellation", "chargeback_prevention", "other" ], "title": "Closed REFUND_REASONS taxonomy", "type": "string" }, "refund_requested_at": { "format": "date-time", "title": "Timestamp when the refund was requested / PSP accepted the request (defaults to now)", "type": "string" }, "refund_trace_reference": { "title": "Network trace reference for cardholder-side traceability (often unavailable at request time, populated by resolve_payment_refund)", "type": "string" }, "refund_trace_reference_type": { "enum": [ "arn", "stan", "rrn", "psp_generated", "unavailable" ], "title": "Type tag on refund_trace_reference", "type": "string" } }, "required": [ "refund_reason", "refund_correlation_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_payment", "hospitality.link.payment_refunds_payment", "hospitality.link.payment_for_reservation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.payment", "hospitality.folio", "hospitality.reservation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Refund payment (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.refund_payment/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_refund_payment`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_refund_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "psp_refund_reference": { "title": "PSP-issued refund reference (Stripe refund.id / Adyen refund pspReference / Checkout.com action_id / Worldpay refund event ref / Braintree refund transaction id / Cybersource credit id / Mews RefundId)", "type": "string" }, "refund_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Refund amount (positive; defaults to remaining refundable balance if unset)", "type": "object" }, "refund_correlation_id": { "title": "Host-side idempotency / reconciliation key (required because two legitimate same-amount partial refunds with the same reason can occur against one payment)", "type": "string" }, "refund_initial_status": { "enum": [ "pending", "refunded" ], "title": "Initial refund leg status: `pending` (PSP accepted but not yet confirmed; defaults to pending) or `refunded` (PSP confirmed synchronously / importing historical confirmed refund)", "type": "string" }, "refund_note": { "title": "Free-form colour, max 1024 chars (required when refund_reason = other)", "type": "string" }, "refund_reason": { "enum": [ "duplicate", "fraudulent", "requested_by_customer", "reservation_cancelled", "deposit_return", "service_recovery", "overcharge_correction", "no_show_policy_exception", "package_component_refund", "membership_cancellation", "chargeback_prevention", "other" ], "title": "Closed REFUND_REASONS taxonomy", "type": "string" }, "refund_requested_at": { "format": "date-time", "title": "Timestamp when the refund was requested / PSP accepted the request (defaults to now)", "type": "string" }, "refund_trace_reference": { "title": "Network trace reference for cardholder-side traceability (often unavailable at request time, populated by resolve_payment_refund)", "type": "string" }, "refund_trace_reference_type": { "enum": [ "arn", "stan", "rrn", "psp_generated", "unavailable" ], "title": "Type tag on refund_trace_reference", "type": "string" } }, "required": [ "refund_reason", "refund_correlation_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Refund payment (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.refund_payment/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_refund_payment` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.refund_payment:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_refund_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "psp_refund_reference": { "title": "PSP-issued refund reference (Stripe refund.id / Adyen refund pspReference / Checkout.com action_id / Worldpay refund event ref / Braintree refund transaction id / Cybersource credit id / Mews RefundId)", "type": "string" }, "refund_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Refund amount (positive; defaults to remaining refundable balance if unset)", "type": "object" }, "refund_correlation_id": { "title": "Host-side idempotency / reconciliation key (required because two legitimate same-amount partial refunds with the same reason can occur against one payment)", "type": "string" }, "refund_initial_status": { "enum": [ "pending", "refunded" ], "title": "Initial refund leg status: `pending` (PSP accepted but not yet confirmed; defaults to pending) or `refunded` (PSP confirmed synchronously / importing historical confirmed refund)", "type": "string" }, "refund_note": { "title": "Free-form colour, max 1024 chars (required when refund_reason = other)", "type": "string" }, "refund_reason": { "enum": [ "duplicate", "fraudulent", "requested_by_customer", "reservation_cancelled", "deposit_return", "service_recovery", "overcharge_correction", "no_show_policy_exception", "package_component_refund", "membership_cancellation", "chargeback_prevention", "other" ], "title": "Closed REFUND_REASONS taxonomy", "type": "string" }, "refund_requested_at": { "format": "date-time", "title": "Timestamp when the refund was requested / PSP accepted the request (defaults to now)", "type": "string" }, "refund_trace_reference": { "title": "Network trace reference for cardholder-side traceability (often unavailable at request time, populated by resolve_payment_refund)", "type": "string" }, "refund_trace_reference_type": { "enum": [ "arn", "stan", "rrn", "psp_generated", "unavailable" ], "title": "Type tag on refund_trace_reference", "type": "string" } }, "required": [ "refund_reason", "refund_correlation_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Refund payment (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.register_agent/apply": { "post": { "description": "Create or supersede an `agent_registry_entry` version. Registry entries declare the maximum scopes an agent claims to need; only `review_status = approved` entries are installable (modulo the `registry_source = manual` operator override). Validators (commit 11): `agent_registry_key_version_unique`, `mcp_remote_requires_https`.\n\nEffects: create hospitality.agent_registry_entry.", "operationId": "apply_hospitality_action_register_agent", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "agent_key": { "title": "Stable registry key", "type": "string" }, "declared_action_scopes": { "items": { "type": "string" }, "title": "Maximum action scopes", "type": "array" }, "declared_data_classes": { "items": { "enum": [ "public", "operational", "guest_pii", "staff_pii", "payment_metadata", "regulated_health", "secrets" ], "type": "string" }, "title": "Data classes the agent processes", "type": "array" }, "declared_function_scopes": { "items": { "type": "string" }, "title": "Maximum function scopes", "type": "array" }, "declared_read_scopes": { "items": { "type": "string" }, "title": "Object types the agent reads, as `objects::read`", "type": "array" }, "declared_risk_tiers": { "items": { "enum": [ "read_only", "internal_write", "guest_message", "money_movement", "identity_or_fraud", "clinical_or_regulated", "other_high_risk" ], "type": "string" }, "title": "Risk tiers the agent claims", "type": "array" }, "definition_document": { "additionalProperties": true, "title": "The runtime-interpreted agent definition (JSON; runtime owns the grammar)", "type": "object" }, "description": { "title": "Bounded to 2048 characters", "type": "string" }, "grounding_scope_ref": { "title": "scope_key of the grounding_scope injected into the retrieval lane (D11)", "type": "string" }, "mcp_server_uri": { "title": "Canonical remote MCP endpoint when applicable (HTTPS only)", "type": "string" }, "model_family": { "title": "Model family", "type": "string" }, "model_provider": { "title": "Model provider", "type": "string" }, "obo_scopes": { "items": { "type": "string" }, "title": "Execute scopes exercisable on behalf of a user; must be a subset of the declared action/function scopes (K5)", "type": "array" }, "package_references": { "title": "Package references (source registry shape)" }, "privacy_url": { "title": "Privacy / DPA documentation", "type": "string" }, "protocols": { "items": { "enum": [ "mcp", "openapi", "webhook", "sdk", "a2a", "custom" ], "type": "string" }, "title": "Protocols the agent supports", "type": "array" }, "publisher": { "title": "Vendor / publisher namespace", "type": "string" }, "registry_record_uri": { "title": "Source registry URL / ARN / id", "type": "string" }, "registry_source": { "enum": [ "aerandil_first_party", "mcp_registry", "aws_agent_registry", "apaleo_agent_hub", "private_registry", "manual" ], "title": "Origin of this registry entry", "type": "string" }, "review_status": { "enum": [ "submitted", "approved", "rejected", "deprecated", "blocked" ], "title": "Curator review status; defaults to submitted", "type": "string" }, "safety_profile": { "title": "Safety / evaluation metadata" }, "security_url": { "title": "Security review docs", "type": "string" }, "title": { "title": "Display name", "type": "string" }, "version": { "title": "Agent version", "type": "string" } }, "required": [ "agent_key", "publisher", "version", "title", "registry_source", "protocols" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.agent_registry_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.register_agent:apply" ] } ], "summary": "Register agent", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.register_agent/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_register_agent` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.register_agent:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_register_agent", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "agent_key": { "title": "Stable registry key", "type": "string" }, "declared_action_scopes": { "items": { "type": "string" }, "title": "Maximum action scopes", "type": "array" }, "declared_data_classes": { "items": { "enum": [ "public", "operational", "guest_pii", "staff_pii", "payment_metadata", "regulated_health", "secrets" ], "type": "string" }, "title": "Data classes the agent processes", "type": "array" }, "declared_function_scopes": { "items": { "type": "string" }, "title": "Maximum function scopes", "type": "array" }, "declared_read_scopes": { "items": { "type": "string" }, "title": "Object types the agent reads, as `objects::read`", "type": "array" }, "declared_risk_tiers": { "items": { "enum": [ "read_only", "internal_write", "guest_message", "money_movement", "identity_or_fraud", "clinical_or_regulated", "other_high_risk" ], "type": "string" }, "title": "Risk tiers the agent claims", "type": "array" }, "definition_document": { "additionalProperties": true, "title": "The runtime-interpreted agent definition (JSON; runtime owns the grammar)", "type": "object" }, "description": { "title": "Bounded to 2048 characters", "type": "string" }, "grounding_scope_ref": { "title": "scope_key of the grounding_scope injected into the retrieval lane (D11)", "type": "string" }, "mcp_server_uri": { "title": "Canonical remote MCP endpoint when applicable (HTTPS only)", "type": "string" }, "model_family": { "title": "Model family", "type": "string" }, "model_provider": { "title": "Model provider", "type": "string" }, "obo_scopes": { "items": { "type": "string" }, "title": "Execute scopes exercisable on behalf of a user; must be a subset of the declared action/function scopes (K5)", "type": "array" }, "package_references": { "title": "Package references (source registry shape)" }, "privacy_url": { "title": "Privacy / DPA documentation", "type": "string" }, "protocols": { "items": { "enum": [ "mcp", "openapi", "webhook", "sdk", "a2a", "custom" ], "type": "string" }, "title": "Protocols the agent supports", "type": "array" }, "publisher": { "title": "Vendor / publisher namespace", "type": "string" }, "registry_record_uri": { "title": "Source registry URL / ARN / id", "type": "string" }, "registry_source": { "enum": [ "aerandil_first_party", "mcp_registry", "aws_agent_registry", "apaleo_agent_hub", "private_registry", "manual" ], "title": "Origin of this registry entry", "type": "string" }, "review_status": { "enum": [ "submitted", "approved", "rejected", "deprecated", "blocked" ], "title": "Curator review status; defaults to submitted", "type": "string" }, "safety_profile": { "title": "Safety / evaluation metadata" }, "security_url": { "title": "Security review docs", "type": "string" }, "title": { "title": "Display name", "type": "string" }, "version": { "title": "Agent version", "type": "string" } }, "required": [ "agent_key", "publisher", "version", "title", "registry_source", "protocols" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.agent_registry_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Register agent (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.register_agent/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_register_agent`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_register_agent", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "agent_key": { "title": "Stable registry key", "type": "string" }, "declared_action_scopes": { "items": { "type": "string" }, "title": "Maximum action scopes", "type": "array" }, "declared_data_classes": { "items": { "enum": [ "public", "operational", "guest_pii", "staff_pii", "payment_metadata", "regulated_health", "secrets" ], "type": "string" }, "title": "Data classes the agent processes", "type": "array" }, "declared_function_scopes": { "items": { "type": "string" }, "title": "Maximum function scopes", "type": "array" }, "declared_read_scopes": { "items": { "type": "string" }, "title": "Object types the agent reads, as `objects::read`", "type": "array" }, "declared_risk_tiers": { "items": { "enum": [ "read_only", "internal_write", "guest_message", "money_movement", "identity_or_fraud", "clinical_or_regulated", "other_high_risk" ], "type": "string" }, "title": "Risk tiers the agent claims", "type": "array" }, "definition_document": { "additionalProperties": true, "title": "The runtime-interpreted agent definition (JSON; runtime owns the grammar)", "type": "object" }, "description": { "title": "Bounded to 2048 characters", "type": "string" }, "grounding_scope_ref": { "title": "scope_key of the grounding_scope injected into the retrieval lane (D11)", "type": "string" }, "mcp_server_uri": { "title": "Canonical remote MCP endpoint when applicable (HTTPS only)", "type": "string" }, "model_family": { "title": "Model family", "type": "string" }, "model_provider": { "title": "Model provider", "type": "string" }, "obo_scopes": { "items": { "type": "string" }, "title": "Execute scopes exercisable on behalf of a user; must be a subset of the declared action/function scopes (K5)", "type": "array" }, "package_references": { "title": "Package references (source registry shape)" }, "privacy_url": { "title": "Privacy / DPA documentation", "type": "string" }, "protocols": { "items": { "enum": [ "mcp", "openapi", "webhook", "sdk", "a2a", "custom" ], "type": "string" }, "title": "Protocols the agent supports", "type": "array" }, "publisher": { "title": "Vendor / publisher namespace", "type": "string" }, "registry_record_uri": { "title": "Source registry URL / ARN / id", "type": "string" }, "registry_source": { "enum": [ "aerandil_first_party", "mcp_registry", "aws_agent_registry", "apaleo_agent_hub", "private_registry", "manual" ], "title": "Origin of this registry entry", "type": "string" }, "review_status": { "enum": [ "submitted", "approved", "rejected", "deprecated", "blocked" ], "title": "Curator review status; defaults to submitted", "type": "string" }, "safety_profile": { "title": "Safety / evaluation metadata" }, "security_url": { "title": "Security review docs", "type": "string" }, "title": { "title": "Display name", "type": "string" }, "version": { "title": "Agent version", "type": "string" } }, "required": [ "agent_key", "publisher", "version", "title", "registry_source", "protocols" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Register agent (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.register_agent/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_register_agent` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.register_agent:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_register_agent", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "agent_key": { "title": "Stable registry key", "type": "string" }, "declared_action_scopes": { "items": { "type": "string" }, "title": "Maximum action scopes", "type": "array" }, "declared_data_classes": { "items": { "enum": [ "public", "operational", "guest_pii", "staff_pii", "payment_metadata", "regulated_health", "secrets" ], "type": "string" }, "title": "Data classes the agent processes", "type": "array" }, "declared_function_scopes": { "items": { "type": "string" }, "title": "Maximum function scopes", "type": "array" }, "declared_read_scopes": { "items": { "type": "string" }, "title": "Object types the agent reads, as `objects::read`", "type": "array" }, "declared_risk_tiers": { "items": { "enum": [ "read_only", "internal_write", "guest_message", "money_movement", "identity_or_fraud", "clinical_or_regulated", "other_high_risk" ], "type": "string" }, "title": "Risk tiers the agent claims", "type": "array" }, "definition_document": { "additionalProperties": true, "title": "The runtime-interpreted agent definition (JSON; runtime owns the grammar)", "type": "object" }, "description": { "title": "Bounded to 2048 characters", "type": "string" }, "grounding_scope_ref": { "title": "scope_key of the grounding_scope injected into the retrieval lane (D11)", "type": "string" }, "mcp_server_uri": { "title": "Canonical remote MCP endpoint when applicable (HTTPS only)", "type": "string" }, "model_family": { "title": "Model family", "type": "string" }, "model_provider": { "title": "Model provider", "type": "string" }, "obo_scopes": { "items": { "type": "string" }, "title": "Execute scopes exercisable on behalf of a user; must be a subset of the declared action/function scopes (K5)", "type": "array" }, "package_references": { "title": "Package references (source registry shape)" }, "privacy_url": { "title": "Privacy / DPA documentation", "type": "string" }, "protocols": { "items": { "enum": [ "mcp", "openapi", "webhook", "sdk", "a2a", "custom" ], "type": "string" }, "title": "Protocols the agent supports", "type": "array" }, "publisher": { "title": "Vendor / publisher namespace", "type": "string" }, "registry_record_uri": { "title": "Source registry URL / ARN / id", "type": "string" }, "registry_source": { "enum": [ "aerandil_first_party", "mcp_registry", "aws_agent_registry", "apaleo_agent_hub", "private_registry", "manual" ], "title": "Origin of this registry entry", "type": "string" }, "review_status": { "enum": [ "submitted", "approved", "rejected", "deprecated", "blocked" ], "title": "Curator review status; defaults to submitted", "type": "string" }, "safety_profile": { "title": "Safety / evaluation metadata" }, "security_url": { "title": "Security review docs", "type": "string" }, "title": { "title": "Display name", "type": "string" }, "version": { "title": "Agent version", "type": "string" } }, "required": [ "agent_key", "publisher", "version", "title", "registry_source", "protocols" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Register agent (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.register_asset/apply": { "post": { "description": "Register a piece of equipment at the house under its code — the house's tag for it, unique within the house. Registering a code the house already holds re-states that asset in place (details replaced, location re-pointed), so the call is replay-safe and is also how an asset is corrected or moved; an identical re-statement changes nothing. A retired code refuses. The asset stands in a room (room_id) or at a venue (venue_id) — one or the other, both of this house — or nowhere in particular. New assets start active.\n\nEffects: create hospitality.asset; modify hospitality.asset; link hospitality.link.asset_in_room; unlink hospitality.link.asset_in_room; link hospitality.link.asset_at_venue; unlink hospitality.link.asset_at_venue.", "operationId": "apply_hospitality_action_register_asset", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "The trade that maintains it", "type": "string" }, "code": { "title": "The house's tag for the asset", "type": "string" }, "description": { "title": "Notes on the asset", "type": "string" }, "installed_year": { "title": "Year of installation", "type": "integer" }, "make": { "title": "Manufacturer", "type": "string" }, "model": { "title": "Model", "type": "string" }, "name": { "title": "What it is, in words", "type": "string" }, "room_id": { "format": "uuid", "title": "The room it is installed in", "type": "string", "x-aerandil-references": "hospitality.room" }, "serial": { "title": "Manufacturer's serial number", "type": "string" }, "venue_id": { "format": "uuid", "title": "The venue it stands at", "type": "string", "x-aerandil-references": "hospitality.venue" } }, "required": [ "code", "name", "category" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.asset_in_room", "hospitality.link.asset_at_venue" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.asset" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.register_asset:apply" ] } ], "summary": "Register asset", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.register_asset/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_register_asset` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.register_asset:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_register_asset", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "The trade that maintains it", "type": "string" }, "code": { "title": "The house's tag for the asset", "type": "string" }, "description": { "title": "Notes on the asset", "type": "string" }, "installed_year": { "title": "Year of installation", "type": "integer" }, "make": { "title": "Manufacturer", "type": "string" }, "model": { "title": "Model", "type": "string" }, "name": { "title": "What it is, in words", "type": "string" }, "room_id": { "format": "uuid", "title": "The room it is installed in", "type": "string", "x-aerandil-references": "hospitality.room" }, "serial": { "title": "Manufacturer's serial number", "type": "string" }, "venue_id": { "format": "uuid", "title": "The venue it stands at", "type": "string", "x-aerandil-references": "hospitality.venue" } }, "required": [ "code", "name", "category" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.asset_in_room", "hospitality.link.asset_at_venue" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.asset" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Register asset (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.register_asset/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_register_asset`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_register_asset", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "The trade that maintains it", "type": "string" }, "code": { "title": "The house's tag for the asset", "type": "string" }, "description": { "title": "Notes on the asset", "type": "string" }, "installed_year": { "title": "Year of installation", "type": "integer" }, "make": { "title": "Manufacturer", "type": "string" }, "model": { "title": "Model", "type": "string" }, "name": { "title": "What it is, in words", "type": "string" }, "room_id": { "format": "uuid", "title": "The room it is installed in", "type": "string", "x-aerandil-references": "hospitality.room" }, "serial": { "title": "Manufacturer's serial number", "type": "string" }, "venue_id": { "format": "uuid", "title": "The venue it stands at", "type": "string", "x-aerandil-references": "hospitality.venue" } }, "required": [ "code", "name", "category" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Register asset (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.register_asset/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_register_asset` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.register_asset:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_register_asset", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "The trade that maintains it", "type": "string" }, "code": { "title": "The house's tag for the asset", "type": "string" }, "description": { "title": "Notes on the asset", "type": "string" }, "installed_year": { "title": "Year of installation", "type": "integer" }, "make": { "title": "Manufacturer", "type": "string" }, "model": { "title": "Model", "type": "string" }, "name": { "title": "What it is, in words", "type": "string" }, "room_id": { "format": "uuid", "title": "The room it is installed in", "type": "string", "x-aerandil-references": "hospitality.room" }, "serial": { "title": "Manufacturer's serial number", "type": "string" }, "venue_id": { "format": "uuid", "title": "The venue it stands at", "type": "string", "x-aerandil-references": "hospitality.venue" } }, "required": [ "code", "name", "category" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Register asset (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.register_connector/apply": { "post": { "description": "Register one external source-system feed (a property's PMS, POS back-end, rostering tool) as a `connector`. Created `active`. `secret_ref` names a credential in the external secret store — never pass the credential itself; `vendor_config` carries only non-secret settings and is validator-guarded against credential-shaped keys. `mapping_refs` pins one versioned mapping definition (name@version) per vendor stream — a tap's whole account rides one connector, because identity-map references between streams are source-scoped. Which stream each mapping consumes, and the order they load in, come from the mapping files. Emits `connector.registered`.\n\nEffects: create hospitality.connector.", "operationId": "apply_hospitality_action_register_connector", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "display_name": { "title": "Human-readable name shown in the Explorer", "type": "string" }, "mapping_refs": { "items": { "type": "string" }, "title": "Mapping definition references, one per vendor stream (name@version)", "type": "array" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "provider": { "title": "Vendor identifier (mews / apaleo / ohip / …)", "type": "string" }, "schedule": { "title": "Intended sync cadence, cron form (informational)", "type": "string" }, "secret_ref": { "title": "Name of the credential in the external secret store (never the value)", "type": "string" }, "source_kind": { "enum": [ "pms", "pos", "rostering", "inventory", "accounting", "distribution", "other" ], "title": "Category of source system", "type": "string" }, "vendor_config": { "additionalProperties": true, "title": "Non-secret vendor settings (base URL, site codes, streams)", "type": "object" } }, "required": [ "display_name", "source_kind", "provider", "mapping_refs" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.connector" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.register_connector:apply" ] } ], "summary": "Register connector", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.register_connector/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_register_connector` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.register_connector:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_register_connector", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "display_name": { "title": "Human-readable name shown in the Explorer", "type": "string" }, "mapping_refs": { "items": { "type": "string" }, "title": "Mapping definition references, one per vendor stream (name@version)", "type": "array" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "provider": { "title": "Vendor identifier (mews / apaleo / ohip / …)", "type": "string" }, "schedule": { "title": "Intended sync cadence, cron form (informational)", "type": "string" }, "secret_ref": { "title": "Name of the credential in the external secret store (never the value)", "type": "string" }, "source_kind": { "enum": [ "pms", "pos", "rostering", "inventory", "accounting", "distribution", "other" ], "title": "Category of source system", "type": "string" }, "vendor_config": { "additionalProperties": true, "title": "Non-secret vendor settings (base URL, site codes, streams)", "type": "object" } }, "required": [ "display_name", "source_kind", "provider", "mapping_refs" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.connector" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Register connector (dry-run)", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.register_connector/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_register_connector`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_register_connector", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "display_name": { "title": "Human-readable name shown in the Explorer", "type": "string" }, "mapping_refs": { "items": { "type": "string" }, "title": "Mapping definition references, one per vendor stream (name@version)", "type": "array" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "provider": { "title": "Vendor identifier (mews / apaleo / ohip / …)", "type": "string" }, "schedule": { "title": "Intended sync cadence, cron form (informational)", "type": "string" }, "secret_ref": { "title": "Name of the credential in the external secret store (never the value)", "type": "string" }, "source_kind": { "enum": [ "pms", "pos", "rostering", "inventory", "accounting", "distribution", "other" ], "title": "Category of source system", "type": "string" }, "vendor_config": { "additionalProperties": true, "title": "Non-secret vendor settings (base URL, site codes, streams)", "type": "object" } }, "required": [ "display_name", "source_kind", "provider", "mapping_refs" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Register connector (dry-run)", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.register_connector/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_register_connector` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.register_connector:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_register_connector", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "display_name": { "title": "Human-readable name shown in the Explorer", "type": "string" }, "mapping_refs": { "items": { "type": "string" }, "title": "Mapping definition references, one per vendor stream (name@version)", "type": "array" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "provider": { "title": "Vendor identifier (mews / apaleo / ohip / …)", "type": "string" }, "schedule": { "title": "Intended sync cadence, cron form (informational)", "type": "string" }, "secret_ref": { "title": "Name of the credential in the external secret store (never the value)", "type": "string" }, "source_kind": { "enum": [ "pms", "pos", "rostering", "inventory", "accounting", "distribution", "other" ], "title": "Category of source system", "type": "string" }, "vendor_config": { "additionalProperties": true, "title": "Non-secret vendor settings (base URL, site codes, streams)", "type": "object" } }, "required": [ "display_name", "source_kind", "provider", "mapping_refs" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Register connector (rollup delta)", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.register_device/apply": { "post": { "description": "Enrol a piece of local hardware (payment terminal, key encoder, kiosk…) at a property, optionally bound to the outlet it serves. Registration is what makes the device an authorisation anchor: `post_charge_by_credential` refuses writes attributed to a device that is not registered and `active`, so an unknown reader cannot post charges. Emits `access.device_registered.recorded`.\n\nEffects: create hospitality.device; link hospitality.link.device_at_property; link hospitality.link.device_at_outlet.", "operationId": "apply_hospitality_action_register_device", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "code": { "title": "Device code", "type": "string" }, "kind": { "enum": [ "payment_terminal", "key_encoder", "door_lock", "kiosk", "printer", "handset", "other" ], "title": "Hardware kind", "type": "string" }, "name": { "title": "Device name", "type": "string" }, "outlet_id": { "format": "uuid", "title": "Revenue center the device serves (payment terminals)", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "print_secret_hash": { "title": "A printer's poll credential: the lowercase hex SHA-256 (64 characters) of the secret its Server Direct Print settings carry — never the secret itself. Printers only.", "type": "string" }, "property_id": { "format": "uuid", "title": "Property where the hardware lives", "type": "string", "x-aerandil-references": "hospitality.property" }, "vendor": { "title": "Hardware / acquirer vendor", "type": "string" }, "vendor_device_ref": { "title": "Vendor-side device identifier", "type": "string" } }, "required": [ "code", "name", "kind", "property_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.device_at_property", "hospitality.link.device_at_outlet" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.device" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.register_device:apply" ] } ], "summary": "Register device", "tags": [ "access" ] } }, "/v1/actions/hospitality.action.register_device/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_register_device` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.register_device:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_register_device", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "code": { "title": "Device code", "type": "string" }, "kind": { "enum": [ "payment_terminal", "key_encoder", "door_lock", "kiosk", "printer", "handset", "other" ], "title": "Hardware kind", "type": "string" }, "name": { "title": "Device name", "type": "string" }, "outlet_id": { "format": "uuid", "title": "Revenue center the device serves (payment terminals)", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "print_secret_hash": { "title": "A printer's poll credential: the lowercase hex SHA-256 (64 characters) of the secret its Server Direct Print settings carry — never the secret itself. Printers only.", "type": "string" }, "property_id": { "format": "uuid", "title": "Property where the hardware lives", "type": "string", "x-aerandil-references": "hospitality.property" }, "vendor": { "title": "Hardware / acquirer vendor", "type": "string" }, "vendor_device_ref": { "title": "Vendor-side device identifier", "type": "string" } }, "required": [ "code", "name", "kind", "property_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.device_at_property", "hospitality.link.device_at_outlet" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.device" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Register device (dry-run)", "tags": [ "access" ] } }, "/v1/actions/hospitality.action.register_device/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_register_device`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_register_device", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "code": { "title": "Device code", "type": "string" }, "kind": { "enum": [ "payment_terminal", "key_encoder", "door_lock", "kiosk", "printer", "handset", "other" ], "title": "Hardware kind", "type": "string" }, "name": { "title": "Device name", "type": "string" }, "outlet_id": { "format": "uuid", "title": "Revenue center the device serves (payment terminals)", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "print_secret_hash": { "title": "A printer's poll credential: the lowercase hex SHA-256 (64 characters) of the secret its Server Direct Print settings carry — never the secret itself. Printers only.", "type": "string" }, "property_id": { "format": "uuid", "title": "Property where the hardware lives", "type": "string", "x-aerandil-references": "hospitality.property" }, "vendor": { "title": "Hardware / acquirer vendor", "type": "string" }, "vendor_device_ref": { "title": "Vendor-side device identifier", "type": "string" } }, "required": [ "code", "name", "kind", "property_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Register device (dry-run)", "tags": [ "access" ] } }, "/v1/actions/hospitality.action.register_device/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_register_device` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.register_device:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_register_device", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "code": { "title": "Device code", "type": "string" }, "kind": { "enum": [ "payment_terminal", "key_encoder", "door_lock", "kiosk", "printer", "handset", "other" ], "title": "Hardware kind", "type": "string" }, "name": { "title": "Device name", "type": "string" }, "outlet_id": { "format": "uuid", "title": "Revenue center the device serves (payment terminals)", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "print_secret_hash": { "title": "A printer's poll credential: the lowercase hex SHA-256 (64 characters) of the secret its Server Direct Print settings carry — never the secret itself. Printers only.", "type": "string" }, "property_id": { "format": "uuid", "title": "Property where the hardware lives", "type": "string", "x-aerandil-references": "hospitality.property" }, "vendor": { "title": "Hardware / acquirer vendor", "type": "string" }, "vendor_device_ref": { "title": "Vendor-side device identifier", "type": "string" } }, "required": [ "code", "name", "kind", "property_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Register device (rollup delta)", "tags": [ "access" ] } }, "/v1/actions/hospitality.action.register_guest/apply": { "post": { "description": "Create a guest `person` from a source-system record, keyed on `external_ref` (`{connector}:{stream}:{external_id}`). Replay-safe: a re-delivery with identical fields is a no-op returning the existing person; the same key with different fields is a conflict (guest identity changes belong to the 0027 steward surface, not to a sync). The front-desk equivalent is creating a guest profile ahead of a booking; the 0037 connector loader drives it once per vendor guest record. Emits `person.guest_registered`.\n\nEffects: create hospitality.person.", "operationId": "apply_hospitality_action_register_guest", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "email": { "title": "Email", "type": "string" }, "external_ref": { "title": "Source-system key — the replay identity for this person", "type": "string" }, "family_name": { "title": "Family name", "type": "string" }, "given_name": { "title": "Given name", "type": "string" }, "phone": { "title": "Phone", "type": "string" } }, "required": [ "external_ref", "given_name", "family_name" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.person" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.register_guest:apply" ] } ], "summary": "Register guest", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.register_guest/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_register_guest` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.register_guest:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_register_guest", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "email": { "title": "Email", "type": "string" }, "external_ref": { "title": "Source-system key — the replay identity for this person", "type": "string" }, "family_name": { "title": "Family name", "type": "string" }, "given_name": { "title": "Given name", "type": "string" }, "phone": { "title": "Phone", "type": "string" } }, "required": [ "external_ref", "given_name", "family_name" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.person" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Register guest (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.register_guest/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_register_guest`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_register_guest", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "email": { "title": "Email", "type": "string" }, "external_ref": { "title": "Source-system key — the replay identity for this person", "type": "string" }, "family_name": { "title": "Family name", "type": "string" }, "given_name": { "title": "Given name", "type": "string" }, "phone": { "title": "Phone", "type": "string" } }, "required": [ "external_ref", "given_name", "family_name" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Register guest (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.register_guest/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_register_guest` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.register_guest:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_register_guest", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "email": { "title": "Email", "type": "string" }, "external_ref": { "title": "Source-system key — the replay identity for this person", "type": "string" }, "family_name": { "title": "Family name", "type": "string" }, "given_name": { "title": "Given name", "type": "string" }, "phone": { "title": "Phone", "type": "string" } }, "required": [ "external_ref", "given_name", "family_name" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Register guest (rollup delta)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.register_outlet/apply": { "post": { "description": "Register a revenue outlet at `property_id` under its `code`, with its `name`, its USALI department (`usali_department`) and operational `kind`; optionally the `usali_revenue_center_label` a revenue report groups it under (the name when absent). Upsert by code: the same code again restates the outlet in place (an identical restatement writes nothing; a field the call does not carry is left alone); a code already registered at another property is refused. Links the outlet to its property (`outlet_at_property`) on first registration. A vendor feed's charges post into the property's sole outlet in each USALI bucket, so a connector's provisioning pass registers one outlet per bucket its lines can land in — rooms, food and beverage, spa, miscellaneous income, other operated — before the first folio line arrives. Emits `outlet.registered`.\n\nEffects: create hospitality.outlet; modify hospitality.outlet; link hospitality.link.outlet_at_property.", "operationId": "apply_hospitality_action_register_outlet", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "code": { "title": "The outlet's code (trimmed; the tenant-unique business key)", "type": "string" }, "kind": { "enum": [ "rooms", "restaurant", "bar", "lounge", "room_service", "banquet", "catering", "spa", "salon", "wellness_program", "gym", "pool", "golf", "parking", "minibar", "retail", "activity", "tour", "rental", "business_center", "laundry", "telecom", "package_aggregator", "other" ], "title": "The outlet's operational kind", "type": "string" }, "name": { "title": "The outlet's name", "type": "string" }, "property_id": { "format": "uuid", "title": "The property the outlet belongs to", "type": "string", "x-aerandil-references": "hospitality.property" }, "usali_department": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "The USALI department the outlet's revenue reports under", "type": "string" }, "usali_revenue_center_label": { "title": "The revenue-centre label a report groups the outlet under (the name when absent)", "type": "string" } }, "required": [ "property_id", "code", "name", "usali_department", "kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.outlet_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.outlet" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.register_outlet:apply" ] } ], "summary": "Register outlet", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.register_outlet/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_register_outlet` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.register_outlet:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_register_outlet", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "code": { "title": "The outlet's code (trimmed; the tenant-unique business key)", "type": "string" }, "kind": { "enum": [ "rooms", "restaurant", "bar", "lounge", "room_service", "banquet", "catering", "spa", "salon", "wellness_program", "gym", "pool", "golf", "parking", "minibar", "retail", "activity", "tour", "rental", "business_center", "laundry", "telecom", "package_aggregator", "other" ], "title": "The outlet's operational kind", "type": "string" }, "name": { "title": "The outlet's name", "type": "string" }, "property_id": { "format": "uuid", "title": "The property the outlet belongs to", "type": "string", "x-aerandil-references": "hospitality.property" }, "usali_department": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "The USALI department the outlet's revenue reports under", "type": "string" }, "usali_revenue_center_label": { "title": "The revenue-centre label a report groups the outlet under (the name when absent)", "type": "string" } }, "required": [ "property_id", "code", "name", "usali_department", "kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.outlet_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.outlet" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Register outlet (dry-run)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.register_outlet/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_register_outlet`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_register_outlet", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "code": { "title": "The outlet's code (trimmed; the tenant-unique business key)", "type": "string" }, "kind": { "enum": [ "rooms", "restaurant", "bar", "lounge", "room_service", "banquet", "catering", "spa", "salon", "wellness_program", "gym", "pool", "golf", "parking", "minibar", "retail", "activity", "tour", "rental", "business_center", "laundry", "telecom", "package_aggregator", "other" ], "title": "The outlet's operational kind", "type": "string" }, "name": { "title": "The outlet's name", "type": "string" }, "property_id": { "format": "uuid", "title": "The property the outlet belongs to", "type": "string", "x-aerandil-references": "hospitality.property" }, "usali_department": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "The USALI department the outlet's revenue reports under", "type": "string" }, "usali_revenue_center_label": { "title": "The revenue-centre label a report groups the outlet under (the name when absent)", "type": "string" } }, "required": [ "property_id", "code", "name", "usali_department", "kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Register outlet (dry-run)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.register_outlet/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_register_outlet` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.register_outlet:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_register_outlet", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "code": { "title": "The outlet's code (trimmed; the tenant-unique business key)", "type": "string" }, "kind": { "enum": [ "rooms", "restaurant", "bar", "lounge", "room_service", "banquet", "catering", "spa", "salon", "wellness_program", "gym", "pool", "golf", "parking", "minibar", "retail", "activity", "tour", "rental", "business_center", "laundry", "telecom", "package_aggregator", "other" ], "title": "The outlet's operational kind", "type": "string" }, "name": { "title": "The outlet's name", "type": "string" }, "property_id": { "format": "uuid", "title": "The property the outlet belongs to", "type": "string", "x-aerandil-references": "hospitality.property" }, "usali_department": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "The USALI department the outlet's revenue reports under", "type": "string" }, "usali_revenue_center_label": { "title": "The revenue-centre label a report groups the outlet under (the name when absent)", "type": "string" } }, "required": [ "property_id", "code", "name", "usali_department", "kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Register outlet (rollup delta)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.register_property/apply": { "post": { "description": "Register a property — the root of a house's inventory — under its `code`, with its `name`, `kind`, IANA `timezone` and `default_currency`; optionally its `legal_name`. Upsert by code: the same code again restates the property in place (an identical restatement writes nothing; a field the call does not carry is left as the house set it). A connector's provisioning pass mints the property from the source PMS's own configuration (a Mews bookable service with the enterprise's timezone and default currency), so a booking that references the vendor's property id resolves on the first sync. Refuses an unknown IANA timezone. Emits `property.registered`.\n\nEffects: create hospitality.property; modify hospitality.property.", "operationId": "apply_hospitality_action_register_property", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "code": { "title": "The property's code (trimmed; the tenant-unique business key — a vendor's property id when a connector provisions it)", "type": "string" }, "default_currency": { "format": "iso-4217", "title": "The house's default currency (ISO 4217)", "type": "string" }, "kind": { "enum": [ "hotel", "resort", "residences", "serviced_apartments", "hostel", "glamping", "mixed_use", "day_spa", "restaurant" ], "title": "What kind of property it is", "type": "string" }, "legal_name": { "title": "The operating entity's legal name, when it differs", "type": "string" }, "name": { "title": "The property's name", "type": "string" }, "timezone": { "title": "The house's IANA timezone (business dates and the night audit run on it)", "type": "string" } }, "required": [ "code", "name", "kind", "timezone", "default_currency" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.property" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.register_property:apply" ] } ], "summary": "Register property", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.register_property/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_register_property` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.register_property:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_register_property", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "code": { "title": "The property's code (trimmed; the tenant-unique business key — a vendor's property id when a connector provisions it)", "type": "string" }, "default_currency": { "format": "iso-4217", "title": "The house's default currency (ISO 4217)", "type": "string" }, "kind": { "enum": [ "hotel", "resort", "residences", "serviced_apartments", "hostel", "glamping", "mixed_use", "day_spa", "restaurant" ], "title": "What kind of property it is", "type": "string" }, "legal_name": { "title": "The operating entity's legal name, when it differs", "type": "string" }, "name": { "title": "The property's name", "type": "string" }, "timezone": { "title": "The house's IANA timezone (business dates and the night audit run on it)", "type": "string" } }, "required": [ "code", "name", "kind", "timezone", "default_currency" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.property" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Register property (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.register_property/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_register_property`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_register_property", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "code": { "title": "The property's code (trimmed; the tenant-unique business key — a vendor's property id when a connector provisions it)", "type": "string" }, "default_currency": { "format": "iso-4217", "title": "The house's default currency (ISO 4217)", "type": "string" }, "kind": { "enum": [ "hotel", "resort", "residences", "serviced_apartments", "hostel", "glamping", "mixed_use", "day_spa", "restaurant" ], "title": "What kind of property it is", "type": "string" }, "legal_name": { "title": "The operating entity's legal name, when it differs", "type": "string" }, "name": { "title": "The property's name", "type": "string" }, "timezone": { "title": "The house's IANA timezone (business dates and the night audit run on it)", "type": "string" } }, "required": [ "code", "name", "kind", "timezone", "default_currency" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Register property (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.register_property/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_register_property` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.register_property:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_register_property", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "code": { "title": "The property's code (trimmed; the tenant-unique business key — a vendor's property id when a connector provisions it)", "type": "string" }, "default_currency": { "format": "iso-4217", "title": "The house's default currency (ISO 4217)", "type": "string" }, "kind": { "enum": [ "hotel", "resort", "residences", "serviced_apartments", "hostel", "glamping", "mixed_use", "day_spa", "restaurant" ], "title": "What kind of property it is", "type": "string" }, "legal_name": { "title": "The operating entity's legal name, when it differs", "type": "string" }, "name": { "title": "The property's name", "type": "string" }, "timezone": { "title": "The house's IANA timezone (business dates and the night audit run on it)", "type": "string" } }, "required": [ "code", "name", "kind", "timezone", "default_currency" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Register property (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.register_public_area/apply": { "post": { "description": "Register a place at the target property that is not a guest room — a lobby, a corridor, a lift, the pool, the staff canteen — under the house's `code` for it, with its `name`, its `kind` (what a checklist template names) and the `floor` it is on. Upsert by code: the same code again restates the area in place (an identical restatement writes nothing; an absent `floor` clears it), and a retired area registered again comes back active. Two first registrations of one code queue on a per-house lock, so the second restates the first. An active area gets one `public_area_clean` per business date from `generate_housekeeping_tasks`. The reader code is `set_public_area_reader_code`'s. Emits `public_area.registered`.\n\nEffects: create hospitality.public_area; modify hospitality.public_area.", "operationId": "apply_hospitality_action_register_public_area", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "code": { "title": "The house's code for the area (trimmed; the business key)", "type": "string" }, "floor": { "title": "The floor it is on, in the rooms' own words", "type": "string" }, "kind": { "enum": [ "lobby", "corridor", "lift", "stairwell", "pool", "gym", "spa_area", "restaurant_floor", "toilets", "back_of_house", "exterior", "other" ], "title": "What kind of place it is", "type": "string" }, "name": { "title": "What the floor calls it", "type": "string" } }, "required": [ "code", "name", "kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.public_area" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.register_public_area:apply" ] } ], "summary": "Register public area", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.register_public_area/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_register_public_area` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.register_public_area:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_register_public_area", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "code": { "title": "The house's code for the area (trimmed; the business key)", "type": "string" }, "floor": { "title": "The floor it is on, in the rooms' own words", "type": "string" }, "kind": { "enum": [ "lobby", "corridor", "lift", "stairwell", "pool", "gym", "spa_area", "restaurant_floor", "toilets", "back_of_house", "exterior", "other" ], "title": "What kind of place it is", "type": "string" }, "name": { "title": "What the floor calls it", "type": "string" } }, "required": [ "code", "name", "kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.public_area" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Register public area (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.register_public_area/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_register_public_area`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_register_public_area", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "code": { "title": "The house's code for the area (trimmed; the business key)", "type": "string" }, "floor": { "title": "The floor it is on, in the rooms' own words", "type": "string" }, "kind": { "enum": [ "lobby", "corridor", "lift", "stairwell", "pool", "gym", "spa_area", "restaurant_floor", "toilets", "back_of_house", "exterior", "other" ], "title": "What kind of place it is", "type": "string" }, "name": { "title": "What the floor calls it", "type": "string" } }, "required": [ "code", "name", "kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Register public area (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.register_public_area/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_register_public_area` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.register_public_area:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_register_public_area", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "code": { "title": "The house's code for the area (trimmed; the business key)", "type": "string" }, "floor": { "title": "The floor it is on, in the rooms' own words", "type": "string" }, "kind": { "enum": [ "lobby", "corridor", "lift", "stairwell", "pool", "gym", "spa_area", "restaurant_floor", "toilets", "back_of_house", "exterior", "other" ], "title": "What kind of place it is", "type": "string" }, "name": { "title": "What the floor calls it", "type": "string" } }, "required": [ "code", "name", "kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Register public area (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.register_rate_plan/apply": { "post": { "description": "Register a rate plan at `property_id` under its `code`, with its `name`, `inclusion` (what a night includes beyond the room) and `currency`; optionally a `description`. Upsert by code: the same code again restates the plan in place (a renamed rate updates, never duplicates; an identical restatement writes nothing; a field the call does not carry is left alone). The code is tenant-unique, so a code already registered at another property is refused. Pricing strategy and yieldability take the type's defaults (open pricing, yieldable) and are set by the revenue surface afterwards. Links the plan to its property (`property_has_rate_plan`) on first registration. A Mews connector provisions one per active rate of the bookable service (`code` == the rate id, `inclusion` room-only — Mews attaches products to a rate rather than naming a board basis, `currency` == the enterprise default). Emits `rate_plan.registered`.\n\nEffects: create hospitality.rate_plan; modify hospitality.rate_plan; link hospitality.link.property_has_rate_plan.", "operationId": "apply_hospitality_action_register_rate_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "code": { "title": "The rate plan's code (trimmed; the tenant-unique business key — a vendor's rate id when a connector provisions it)", "type": "string" }, "currency": { "format": "iso-4217", "title": "The currency the plan is priced in (ISO 4217)", "type": "string" }, "description": { "title": "A description of the plan", "type": "string" }, "inclusion": { "enum": [ "room_only", "breakfast", "half_board", "full_board", "all_inclusive" ], "title": "What a night on the plan includes beyond the room", "type": "string" }, "name": { "title": "The rate plan's name", "type": "string" }, "property_id": { "format": "uuid", "title": "The property the rate plan is sold at", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "property_id", "code", "name", "inclusion", "currency" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.property_has_rate_plan" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.rate_plan" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.register_rate_plan:apply" ] } ], "summary": "Register rate plan", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.register_rate_plan/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_register_rate_plan` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.register_rate_plan:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_register_rate_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "code": { "title": "The rate plan's code (trimmed; the tenant-unique business key — a vendor's rate id when a connector provisions it)", "type": "string" }, "currency": { "format": "iso-4217", "title": "The currency the plan is priced in (ISO 4217)", "type": "string" }, "description": { "title": "A description of the plan", "type": "string" }, "inclusion": { "enum": [ "room_only", "breakfast", "half_board", "full_board", "all_inclusive" ], "title": "What a night on the plan includes beyond the room", "type": "string" }, "name": { "title": "The rate plan's name", "type": "string" }, "property_id": { "format": "uuid", "title": "The property the rate plan is sold at", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "property_id", "code", "name", "inclusion", "currency" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.property_has_rate_plan" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.rate_plan" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Register rate plan (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.register_rate_plan/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_register_rate_plan`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_register_rate_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "code": { "title": "The rate plan's code (trimmed; the tenant-unique business key — a vendor's rate id when a connector provisions it)", "type": "string" }, "currency": { "format": "iso-4217", "title": "The currency the plan is priced in (ISO 4217)", "type": "string" }, "description": { "title": "A description of the plan", "type": "string" }, "inclusion": { "enum": [ "room_only", "breakfast", "half_board", "full_board", "all_inclusive" ], "title": "What a night on the plan includes beyond the room", "type": "string" }, "name": { "title": "The rate plan's name", "type": "string" }, "property_id": { "format": "uuid", "title": "The property the rate plan is sold at", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "property_id", "code", "name", "inclusion", "currency" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Register rate plan (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.register_rate_plan/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_register_rate_plan` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.register_rate_plan:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_register_rate_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "code": { "title": "The rate plan's code (trimmed; the tenant-unique business key — a vendor's rate id when a connector provisions it)", "type": "string" }, "currency": { "format": "iso-4217", "title": "The currency the plan is priced in (ISO 4217)", "type": "string" }, "description": { "title": "A description of the plan", "type": "string" }, "inclusion": { "enum": [ "room_only", "breakfast", "half_board", "full_board", "all_inclusive" ], "title": "What a night on the plan includes beyond the room", "type": "string" }, "name": { "title": "The rate plan's name", "type": "string" }, "property_id": { "format": "uuid", "title": "The property the rate plan is sold at", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "property_id", "code", "name", "inclusion", "currency" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Register rate plan (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.register_room/apply": { "post": { "description": "Register a physical room at `property_id` in `room_type_id` under its vendor-alignment `code`, with its `number` (what the house calls it) and optionally its `floor`. Upsert by code: the same code again restates the room in place — a renumbered room updates, a re-categorised room moves to the new type (`room_type_has_room` is re-pointed), an identical restatement writes nothing. The room type must belong to the property. The state axes are the house's, not the feed's: `housekeeping_status` is honoured only on first registration (the room's state on day 0; `dirty` when absent) and never overwritten by a restatement, and `occupancy` starts `vacant` and is written only by check-in / check-out. Links the room to its property and its type on first registration. A Mews connector provisions one per resource assigned to a category of the bookable service (`code` == the resource id, `number` == its name). Emits `room.registered`.\n\nEffects: create hospitality.room; modify hospitality.room; link hospitality.link.property_has_room; link hospitality.link.room_type_has_room; unlink hospitality.link.room_type_has_room.", "operationId": "apply_hospitality_action_register_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "bed_configuration": { "enum": [ "joined", "split" ], "title": "How the room's convertible beds are made up now, when known", "type": "string" }, "code": { "title": "The room's vendor-alignment code (trimmed; the tenant-unique business key — a vendor's unit id when a connector provisions it)", "type": "string" }, "floor": { "title": "The floor it is on, in the house's own words", "type": "string" }, "housekeeping_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "The room's cleaning state on first registration only (`dirty` when absent)", "type": "string" }, "number": { "title": "The room number — what the house calls the room", "type": "string" }, "property_id": { "format": "uuid", "title": "The property the room is in", "type": "string", "x-aerandil-references": "hospitality.property" }, "room_type_id": { "format": "uuid", "title": "The room type the room sells as (must belong to the property)", "type": "string", "x-aerandil-references": "hospitality.room_type" } }, "required": [ "property_id", "room_type_id", "code", "number" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.property_has_room", "hospitality.link.room_type_has_room" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.room" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.register_room:apply" ] } ], "summary": "Register room", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.register_room/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_register_room` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.register_room:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_register_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "bed_configuration": { "enum": [ "joined", "split" ], "title": "How the room's convertible beds are made up now, when known", "type": "string" }, "code": { "title": "The room's vendor-alignment code (trimmed; the tenant-unique business key — a vendor's unit id when a connector provisions it)", "type": "string" }, "floor": { "title": "The floor it is on, in the house's own words", "type": "string" }, "housekeeping_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "The room's cleaning state on first registration only (`dirty` when absent)", "type": "string" }, "number": { "title": "The room number — what the house calls the room", "type": "string" }, "property_id": { "format": "uuid", "title": "The property the room is in", "type": "string", "x-aerandil-references": "hospitality.property" }, "room_type_id": { "format": "uuid", "title": "The room type the room sells as (must belong to the property)", "type": "string", "x-aerandil-references": "hospitality.room_type" } }, "required": [ "property_id", "room_type_id", "code", "number" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.property_has_room", "hospitality.link.room_type_has_room" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.room" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Register room (dry-run)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.register_room/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_register_room`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_register_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "bed_configuration": { "enum": [ "joined", "split" ], "title": "How the room's convertible beds are made up now, when known", "type": "string" }, "code": { "title": "The room's vendor-alignment code (trimmed; the tenant-unique business key — a vendor's unit id when a connector provisions it)", "type": "string" }, "floor": { "title": "The floor it is on, in the house's own words", "type": "string" }, "housekeeping_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "The room's cleaning state on first registration only (`dirty` when absent)", "type": "string" }, "number": { "title": "The room number — what the house calls the room", "type": "string" }, "property_id": { "format": "uuid", "title": "The property the room is in", "type": "string", "x-aerandil-references": "hospitality.property" }, "room_type_id": { "format": "uuid", "title": "The room type the room sells as (must belong to the property)", "type": "string", "x-aerandil-references": "hospitality.room_type" } }, "required": [ "property_id", "room_type_id", "code", "number" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Register room (dry-run)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.register_room/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_register_room` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.register_room:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_register_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "bed_configuration": { "enum": [ "joined", "split" ], "title": "How the room's convertible beds are made up now, when known", "type": "string" }, "code": { "title": "The room's vendor-alignment code (trimmed; the tenant-unique business key — a vendor's unit id when a connector provisions it)", "type": "string" }, "floor": { "title": "The floor it is on, in the house's own words", "type": "string" }, "housekeeping_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "The room's cleaning state on first registration only (`dirty` when absent)", "type": "string" }, "number": { "title": "The room number — what the house calls the room", "type": "string" }, "property_id": { "format": "uuid", "title": "The property the room is in", "type": "string", "x-aerandil-references": "hospitality.property" }, "room_type_id": { "format": "uuid", "title": "The room type the room sells as (must belong to the property)", "type": "string", "x-aerandil-references": "hospitality.room_type" } }, "required": [ "property_id", "room_type_id", "code", "number" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Register room (rollup delta)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.register_room_type/apply": { "post": { "description": "Register a room type at `property_id` under its `code`, with its `name` and `max_occupancy`; optionally a `description` and the `bed_configuration` it sells as. Upsert by code: the same code again restates the type in place — a renamed category updates, never duplicates; an identical restatement writes nothing; a field the call does not carry is left alone. The code is tenant-unique, so a code already registered at another property is refused rather than moved. Links the type to its property (`property_has_room_type`) on first registration. A Mews connector provisions one per resource category (`code` == the category id, `max_occupancy` == its capacity). Emits `room_type.registered`.\n\nEffects: create hospitality.room_type; modify hospitality.room_type; link hospitality.link.property_has_room_type.", "operationId": "apply_hospitality_action_register_room_type", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "bed_configuration": { "title": "The bed configuration the type sells as, in the house's words", "type": "string" }, "code": { "title": "The room type's code (trimmed; the tenant-unique business key — a vendor's category id when a connector provisions it)", "type": "string" }, "description": { "title": "A description of the type", "type": "string" }, "max_occupancy": { "title": "How many guests a room of this type sleeps (at least one)", "type": "integer" }, "name": { "title": "The room type's name", "type": "string" }, "property_id": { "format": "uuid", "title": "The property the room type belongs to", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "property_id", "code", "name", "max_occupancy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.property_has_room_type" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.room_type" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.register_room_type:apply" ] } ], "summary": "Register room type", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.register_room_type/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_register_room_type` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.register_room_type:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_register_room_type", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "bed_configuration": { "title": "The bed configuration the type sells as, in the house's words", "type": "string" }, "code": { "title": "The room type's code (trimmed; the tenant-unique business key — a vendor's category id when a connector provisions it)", "type": "string" }, "description": { "title": "A description of the type", "type": "string" }, "max_occupancy": { "title": "How many guests a room of this type sleeps (at least one)", "type": "integer" }, "name": { "title": "The room type's name", "type": "string" }, "property_id": { "format": "uuid", "title": "The property the room type belongs to", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "property_id", "code", "name", "max_occupancy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.property_has_room_type" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.room_type" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Register room type (dry-run)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.register_room_type/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_register_room_type`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_register_room_type", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "bed_configuration": { "title": "The bed configuration the type sells as, in the house's words", "type": "string" }, "code": { "title": "The room type's code (trimmed; the tenant-unique business key — a vendor's category id when a connector provisions it)", "type": "string" }, "description": { "title": "A description of the type", "type": "string" }, "max_occupancy": { "title": "How many guests a room of this type sleeps (at least one)", "type": "integer" }, "name": { "title": "The room type's name", "type": "string" }, "property_id": { "format": "uuid", "title": "The property the room type belongs to", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "property_id", "code", "name", "max_occupancy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Register room type (dry-run)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.register_room_type/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_register_room_type` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.register_room_type:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_register_room_type", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "bed_configuration": { "title": "The bed configuration the type sells as, in the house's words", "type": "string" }, "code": { "title": "The room type's code (trimmed; the tenant-unique business key — a vendor's category id when a connector provisions it)", "type": "string" }, "description": { "title": "A description of the type", "type": "string" }, "max_occupancy": { "title": "How many guests a room of this type sleeps (at least one)", "type": "integer" }, "name": { "title": "The room type's name", "type": "string" }, "property_id": { "format": "uuid", "title": "The property the room type belongs to", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "property_id", "code", "name", "max_occupancy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Register room type (rollup delta)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.reject_channel_reservation/apply": { "post": { "description": "Permanently refuse a message — an unmapped room type or rate plan, an unknown property, a malformed payload. Permanence is the point and is dictated by the wire: SiteMinder reads an error response as a final decision, stops retrying, and emails the property. So this verb is only for faults that will still be faults on the tenth attempt. A transient problem must leave the delivery `failed` and unacknowledged instead, so redelivery can fix it. Emits `channel_reservation.rejected`.\n\nEffects: modify hospitality.channel_reservation_delivery.", "operationId": "apply_hospitality_action_reject_channel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_detail": { "title": "Operator-facing detail behind the rejection", "type": "string" }, "rejection_kind": { "enum": [ "unmapped_room_type", "unmapped_rate_plan", "unknown_property", "connection_inactive", "invalid_stay_dates", "malformed_payload", "business_rule", "other" ], "title": "Why the message was permanently refused", "type": "string" } }, "required": [ "rejection_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_reservation_delivery" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.channel_reservation_delivery" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.reject_channel_reservation:apply" ] } ], "summary": "Reject channel reservation", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.reject_channel_reservation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_reject_channel_reservation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.reject_channel_reservation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_reject_channel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_detail": { "title": "Operator-facing detail behind the rejection", "type": "string" }, "rejection_kind": { "enum": [ "unmapped_room_type", "unmapped_rate_plan", "unknown_property", "connection_inactive", "invalid_stay_dates", "malformed_payload", "business_rule", "other" ], "title": "Why the message was permanently refused", "type": "string" } }, "required": [ "rejection_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_reservation_delivery" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.channel_reservation_delivery" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Reject channel reservation (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.reject_channel_reservation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_reject_channel_reservation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_reject_channel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_detail": { "title": "Operator-facing detail behind the rejection", "type": "string" }, "rejection_kind": { "enum": [ "unmapped_room_type", "unmapped_rate_plan", "unknown_property", "connection_inactive", "invalid_stay_dates", "malformed_payload", "business_rule", "other" ], "title": "Why the message was permanently refused", "type": "string" } }, "required": [ "rejection_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_reservation_delivery" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Reject channel reservation (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.reject_channel_reservation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_reject_channel_reservation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.reject_channel_reservation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_reject_channel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_detail": { "title": "Operator-facing detail behind the rejection", "type": "string" }, "rejection_kind": { "enum": [ "unmapped_room_type", "unmapped_rate_plan", "unknown_property", "connection_inactive", "invalid_stay_dates", "malformed_payload", "business_rule", "other" ], "title": "Why the message was permanently refused", "type": "string" } }, "required": [ "rejection_kind" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_reservation_delivery" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Reject channel reservation (rollup delta)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.reject_fraud_assessment/apply": { "post": { "description": "Decline a suggested fraud_risk_assessment (treat as false positive). Transitions `decision_status` to `rejected` and records an optional free-text reason for the multi-metric trust-formation instrumentation. Rejected if the assessment isn't in `suggested` state.\n\nEffects: modify hospitality.fraud_risk_assessment.", "operationId": "apply_hospitality_action_reject_fraud_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Free-text reason (optional)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fraud_risk_assessment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.fraud_risk_assessment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.reject_fraud_assessment:apply" ] } ], "summary": "Reject fraud assessment", "tags": [ "fraud_detection" ] } }, "/v1/actions/hospitality.action.reject_fraud_assessment/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_reject_fraud_assessment` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.reject_fraud_assessment:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_reject_fraud_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Free-text reason (optional)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fraud_risk_assessment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.fraud_risk_assessment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Reject fraud assessment (dry-run)", "tags": [ "fraud_detection" ] } }, "/v1/actions/hospitality.action.reject_fraud_assessment/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_reject_fraud_assessment`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_reject_fraud_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Free-text reason (optional)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fraud_risk_assessment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Reject fraud assessment (dry-run)", "tags": [ "fraud_detection" ] } }, "/v1/actions/hospitality.action.reject_fraud_assessment/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_reject_fraud_assessment` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.reject_fraud_assessment:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_reject_fraud_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Free-text reason (optional)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fraud_risk_assessment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Reject fraud assessment (rollup delta)", "tags": [ "fraud_detection" ] } }, "/v1/actions/hospitality.action.reject_message_triage/apply": { "post": { "description": "Decline a suggested message_triage. Transitions `decision_status` to `rejected` and records an optional free-text reason for the multi-metric trust-formation instrumentation (proposal 0014 §10.7). Rejected if the triage isn't in `suggested` state.\n\nEffects: modify hospitality.message_triage; modify hospitality.guest_conversation.", "operationId": "apply_hospitality_action_reject_message_triage", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Free-text reason (optional)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.message_triage" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.message_triage", "hospitality.guest_conversation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.reject_message_triage:apply" ] } ], "summary": "Reject message triage", "tags": [ "messaging" ] } }, "/v1/actions/hospitality.action.reject_message_triage/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_reject_message_triage` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.reject_message_triage:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_reject_message_triage", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Free-text reason (optional)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.message_triage" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.message_triage", "hospitality.guest_conversation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Reject message triage (dry-run)", "tags": [ "messaging" ] } }, "/v1/actions/hospitality.action.reject_message_triage/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_reject_message_triage`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_reject_message_triage", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Free-text reason (optional)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.message_triage" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Reject message triage (dry-run)", "tags": [ "messaging" ] } }, "/v1/actions/hospitality.action.reject_message_triage/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_reject_message_triage` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.reject_message_triage:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_reject_message_triage", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Free-text reason (optional)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.message_triage" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Reject message triage (rollup delta)", "tags": [ "messaging" ] } }, "/v1/actions/hospitality.action.reject_pattern_assessment/apply": { "post": { "description": "Reject a suggested service_recovery_pattern — the operator judges the detected recurring failure not real or not worth acting on. Terminal transition out of suggested.\n\nEffects: modify hospitality.service_recovery_pattern; modify hospitality.recovery_pattern_detection_run.", "operationId": "apply_hospitality_action_reject_pattern_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Free-text rejection reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_recovery_pattern" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.service_recovery_pattern", "hospitality.recovery_pattern_detection_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.reject_pattern_assessment:apply" ] } ], "summary": "Reject pattern assessment", "tags": [ "recovery_pattern_detection" ] } }, "/v1/actions/hospitality.action.reject_pattern_assessment/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_reject_pattern_assessment` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.reject_pattern_assessment:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_reject_pattern_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Free-text rejection reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_recovery_pattern" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.service_recovery_pattern", "hospitality.recovery_pattern_detection_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Reject pattern assessment (dry-run)", "tags": [ "recovery_pattern_detection" ] } }, "/v1/actions/hospitality.action.reject_pattern_assessment/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_reject_pattern_assessment`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_reject_pattern_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Free-text rejection reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_recovery_pattern" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Reject pattern assessment (dry-run)", "tags": [ "recovery_pattern_detection" ] } }, "/v1/actions/hospitality.action.reject_pattern_assessment/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_reject_pattern_assessment` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.reject_pattern_assessment:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_reject_pattern_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Free-text rejection reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_recovery_pattern" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Reject pattern assessment (rollup delta)", "tags": [ "recovery_pattern_detection" ] } }, "/v1/actions/hospitality.action.reject_person_match/apply": { "post": { "description": "Decline a pending candidate: a human looked and said \"not the same\". Terminal and permanent — the pair is suppressed from re-proposal (only a `manual` re-propose overrides, proposal 0027 §8.3). The candidate row stays as the audit record of the decision. Emits `person.match_rejected`.\n\nEffects: modify hospitality.person_merge_candidate.", "operationId": "apply_hospitality_action_reject_person_match", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person_merge_candidate" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.person_merge_candidate" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.reject_person_match:apply" ] } ], "summary": "Reject person match", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.reject_person_match/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_reject_person_match` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.reject_person_match:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_reject_person_match", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person_merge_candidate" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.person_merge_candidate" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Reject person match (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.reject_person_match/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_reject_person_match`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_reject_person_match", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person_merge_candidate" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Reject person match (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.reject_person_match/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_reject_person_match` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.reject_person_match:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_reject_person_match", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person_merge_candidate" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Reject person match (rollup delta)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.reject_proposed_action/apply": { "post": { "description": "The confirmer declines a `proposed_action`, transitioning it to `rejected`. Emits `proposed_action.rejected`.\n\nEffects: modify hospitality.proposed_action.", "operationId": "apply_hospitality_action_reject_proposed_action", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Optional reason the proposal was declined", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.proposed_action" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.proposed_action" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.reject_proposed_action:apply" ] } ], "summary": "Reject proposed action", "tags": [ "proposed_action" ] } }, "/v1/actions/hospitality.action.reject_proposed_action/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_reject_proposed_action` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.reject_proposed_action:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_reject_proposed_action", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Optional reason the proposal was declined", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.proposed_action" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.proposed_action" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Reject proposed action (dry-run)", "tags": [ "proposed_action" ] } }, "/v1/actions/hospitality.action.reject_proposed_action/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_reject_proposed_action`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_reject_proposed_action", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Optional reason the proposal was declined", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.proposed_action" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Reject proposed action (dry-run)", "tags": [ "proposed_action" ] } }, "/v1/actions/hospitality.action.reject_proposed_action/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_reject_proposed_action` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.reject_proposed_action:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_reject_proposed_action", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Optional reason the proposal was declined", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.proposed_action" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Reject proposed action (rollup delta)", "tags": [ "proposed_action" ] } }, "/v1/actions/hospitality.action.reject_rate_recommendation/apply": { "post": { "description": "Decline a suggested rate_recommendation. Transitions `decision_status` to `rejected` and records an optional free-text reason for override-rate analytics. Rejected if the recommendation isn't in `suggested` state.\n\nEffects: modify hospitality.rate_recommendation; modify hospitality.rate_recommendation_run.", "operationId": "apply_hospitality_action_reject_rate_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Free-text reason (optional)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_recommendation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.rate_recommendation", "hospitality.rate_recommendation_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.reject_rate_recommendation:apply" ] } ], "summary": "Reject rate recommendation", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.reject_rate_recommendation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_reject_rate_recommendation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.reject_rate_recommendation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_reject_rate_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Free-text reason (optional)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_recommendation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.rate_recommendation", "hospitality.rate_recommendation_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Reject rate recommendation (dry-run)", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.reject_rate_recommendation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_reject_rate_recommendation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_reject_rate_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Free-text reason (optional)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_recommendation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Reject rate recommendation (dry-run)", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.reject_rate_recommendation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_reject_rate_recommendation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.reject_rate_recommendation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_reject_rate_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Free-text reason (optional)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_recommendation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Reject rate recommendation (rollup delta)", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.reject_restriction_recommendation/apply": { "post": { "description": "Decline a suggested restriction_recommendation. Transitions `decision_status` to `rejected` and records an optional free-text reason for override-rate analytics. Rejected if the recommendation isn't in `suggested` state.\n\nEffects: modify hospitality.restriction_recommendation; modify hospitality.rate_recommendation_run.", "operationId": "apply_hospitality_action_reject_restriction_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Free-text reason (optional)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.restriction_recommendation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.restriction_recommendation", "hospitality.rate_recommendation_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.reject_restriction_recommendation:apply" ] } ], "summary": "Reject restriction recommendation", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.reject_restriction_recommendation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_reject_restriction_recommendation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.reject_restriction_recommendation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_reject_restriction_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Free-text reason (optional)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.restriction_recommendation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.restriction_recommendation", "hospitality.rate_recommendation_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Reject restriction recommendation (dry-run)", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.reject_restriction_recommendation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_reject_restriction_recommendation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_reject_restriction_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Free-text reason (optional)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.restriction_recommendation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Reject restriction recommendation (dry-run)", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.reject_restriction_recommendation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_reject_restriction_recommendation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.reject_restriction_recommendation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_reject_restriction_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Free-text reason (optional)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.restriction_recommendation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Reject restriction recommendation (rollup delta)", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.reject_sell_limit_recommendation/apply": { "post": { "description": "Decline a suggested sell_limit_recommendation. Transitions `decision_status` to `rejected` and records an optional free-text reason for override-rate analytics; the ledger is untouched. Rejected if the recommendation isn't in `suggested` state.\n\nEffects: modify hospitality.sell_limit_recommendation; modify hospitality.rate_recommendation_run.", "operationId": "apply_hospitality_action_reject_sell_limit_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Free-text reason (optional)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.sell_limit_recommendation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.sell_limit_recommendation", "hospitality.rate_recommendation_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.reject_sell_limit_recommendation:apply" ] } ], "summary": "Reject sell-limit recommendation", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.reject_sell_limit_recommendation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_reject_sell_limit_recommendation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.reject_sell_limit_recommendation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_reject_sell_limit_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Free-text reason (optional)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.sell_limit_recommendation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.sell_limit_recommendation", "hospitality.rate_recommendation_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Reject sell-limit recommendation (dry-run)", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.reject_sell_limit_recommendation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_reject_sell_limit_recommendation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_reject_sell_limit_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Free-text reason (optional)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.sell_limit_recommendation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Reject sell-limit recommendation (dry-run)", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.reject_sell_limit_recommendation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_reject_sell_limit_recommendation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.reject_sell_limit_recommendation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_reject_sell_limit_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "rejection_reason": { "title": "Free-text reason (optional)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.sell_limit_recommendation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Reject sell-limit recommendation (rollup delta)", "tags": [ "revenue_management" ] } }, "/v1/actions/hospitality.action.release_block/apply": { "post": { "description": "Return rooms the block is holding but nobody picked up to house availability. Without `through_date` every night is released; with it, only nights on or before that date — the shape a rolling cutoff needs. Safe to repeat: the amount released is recomputed from each cell, so a second run releases nothing.\n\nEffects: modify hospitality.block_allocation; modify hospitality.availability_day.", "operationId": "apply_hospitality_action_release_block", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the rooms were released", "type": "string" }, "through_date": { "format": "date", "title": "Release nights on or before this date (default: all nights)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_block" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.block_allocation", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.release_block:apply" ] } ], "summary": "Release block rooms", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.release_block/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_release_block` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.release_block:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_release_block", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the rooms were released", "type": "string" }, "through_date": { "format": "date", "title": "Release nights on or before this date (default: all nights)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_block" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.block_allocation", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Release block rooms (dry-run)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.release_block/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_release_block`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_release_block", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the rooms were released", "type": "string" }, "through_date": { "format": "date", "title": "Release nights on or before this date (default: all nights)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_block" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Release block rooms (dry-run)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.release_block/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_release_block` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.release_block:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_release_block", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the rooms were released", "type": "string" }, "through_date": { "format": "date", "title": "Release nights on or before this date (default: all nights)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_block" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Release block rooms (rollup delta)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.release_commission_hold/apply": { "post": { "description": "Return a held commission row to `accrued`, where the next payment run will see it.\n\nEffects: modify hospitality.commission_detail.", "operationId": "apply_hospitality_action_release_commission_hold", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.commission_detail" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.commission_detail" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.release_commission_hold:apply" ] } ], "summary": "Release commission hold", "tags": [ "commission" ] } }, "/v1/actions/hospitality.action.release_commission_hold/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_release_commission_hold` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.release_commission_hold:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_release_commission_hold", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.commission_detail" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.commission_detail" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Release commission hold (dry-run)", "tags": [ "commission" ] } }, "/v1/actions/hospitality.action.release_commission_hold/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_release_commission_hold`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_release_commission_hold", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.commission_detail" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Release commission hold (dry-run)", "tags": [ "commission" ] } }, "/v1/actions/hospitality.action.release_commission_hold/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_release_commission_hold` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.release_commission_hold:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_release_commission_hold", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.commission_detail" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Release commission hold (rollup delta)", "tags": [ "commission" ] } }, "/v1/actions/hospitality.action.release_object_property_pin/apply": { "post": { "description": "Remove a property's pin: from the next sync on, sourced writes may overwrite the property again. Idempotent — releasing an unpinned property is a no-op. The release is itself audited (`object_property.pin_released`); the pin's history stays in the event log.", "operationId": "apply_hospitality_action_release_object_property_pin", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "object_id": { "title": "Object id", "type": "string" }, "object_type": { "title": "Object type carrying the property", "type": "string" }, "property": { "title": "Property whose pin to release", "type": "string" } }, "required": [ "object_type", "object_id", "property" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.release_object_property_pin:apply" ] } ], "summary": "Release object property pin", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.release_object_property_pin/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_release_object_property_pin` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.release_object_property_pin:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_release_object_property_pin", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "object_id": { "title": "Object id", "type": "string" }, "object_type": { "title": "Object type carrying the property", "type": "string" }, "property": { "title": "Property whose pin to release", "type": "string" } }, "required": [ "object_type", "object_id", "property" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Release object property pin (dry-run)", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.release_object_property_pin/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_release_object_property_pin`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_release_object_property_pin", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "object_id": { "title": "Object id", "type": "string" }, "object_type": { "title": "Object type carrying the property", "type": "string" }, "property": { "title": "Property whose pin to release", "type": "string" } }, "required": [ "object_type", "object_id", "property" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Release object property pin (dry-run)", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.release_object_property_pin/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_release_object_property_pin` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.release_object_property_pin:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_release_object_property_pin", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "object_id": { "title": "Object id", "type": "string" }, "object_type": { "title": "Object type carrying the property", "type": "string" }, "property": { "title": "Property whose pin to release", "type": "string" } }, "required": [ "object_type", "object_id", "property" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Release object property pin (rollup delta)", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.remove_banquet_order_line/apply": { "post": { "description": "Take a line off the order. Removing from an issued order marks it `revised`; a posted or cancelled order's lines are frozen.\n\nEffects: delete hospitality.banquet_order_line; modify hospitality.banquet_event_order; unlink hospitality.link.banquet_order_has_line; unlink hospitality.link.banquet_order_line_for_service_item.", "operationId": "apply_hospitality_action_remove_banquet_order_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_order_line" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.banquet_order_has_line", "hospitality.link.banquet_order_line_for_service_item" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "deleted", "modified" ] }, "object_type": { "enum": [ "hospitality.banquet_order_line", "hospitality.banquet_event_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.remove_banquet_order_line:apply" ] } ], "summary": "Remove banquet order line", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.remove_banquet_order_line/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_remove_banquet_order_line` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.remove_banquet_order_line:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_remove_banquet_order_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_order_line" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.banquet_order_has_line", "hospitality.link.banquet_order_line_for_service_item" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "deleted", "modified" ] }, "object_type": { "enum": [ "hospitality.banquet_order_line", "hospitality.banquet_event_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Remove banquet order line (dry-run)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.remove_banquet_order_line/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_remove_banquet_order_line`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_remove_banquet_order_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_order_line" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Remove banquet order line (dry-run)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.remove_banquet_order_line/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_remove_banquet_order_line` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.remove_banquet_order_line:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_remove_banquet_order_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_order_line" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Remove banquet order line (rollup delta)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.renew_membership/apply": { "post": { "description": "Advance the subscription's next billing date and optionally transition cadence. The dues charge that results flows through Aerandil's existing `charge` model attached to the appropriate USALI outlet (per proposal 0001); this action records the contract-side advancement, not the charge posting itself.\n\nEffects: modify hospitality.membership_subscription.", "operationId": "apply_hospitality_action_renew_membership", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "new_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Updated amount (optional — set on rate revision)", "type": "object" }, "new_cadence": { "enum": [ "monthly", "quarterly", "semi_annual", "annual", "multi_year" ], "title": "Updated cadence (optional — typically same as current)", "type": "string" }, "next_billing_date": { "format": "date", "title": "New next-billing-date", "type": "string" } }, "required": [ "next_billing_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership_subscription" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.membership_subscription" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.renew_membership:apply" ] } ], "summary": "Renew membership", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.renew_membership/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_renew_membership` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.renew_membership:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_renew_membership", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "new_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Updated amount (optional — set on rate revision)", "type": "object" }, "new_cadence": { "enum": [ "monthly", "quarterly", "semi_annual", "annual", "multi_year" ], "title": "Updated cadence (optional — typically same as current)", "type": "string" }, "next_billing_date": { "format": "date", "title": "New next-billing-date", "type": "string" } }, "required": [ "next_billing_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership_subscription" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.membership_subscription" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Renew membership (dry-run)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.renew_membership/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_renew_membership`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_renew_membership", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "new_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Updated amount (optional — set on rate revision)", "type": "object" }, "new_cadence": { "enum": [ "monthly", "quarterly", "semi_annual", "annual", "multi_year" ], "title": "Updated cadence (optional — typically same as current)", "type": "string" }, "next_billing_date": { "format": "date", "title": "New next-billing-date", "type": "string" } }, "required": [ "next_billing_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership_subscription" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Renew membership (dry-run)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.renew_membership/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_renew_membership` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.renew_membership:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_renew_membership", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "new_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Updated amount (optional — set on rate revision)", "type": "object" }, "new_cadence": { "enum": [ "monthly", "quarterly", "semi_annual", "annual", "multi_year" ], "title": "Updated cadence (optional — typically same as current)", "type": "string" }, "next_billing_date": { "format": "date", "title": "New next-billing-date", "type": "string" } }, "required": [ "next_billing_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership_subscription" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Renew membership (rollup delta)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.reopen_folio/apply": { "post": { "description": "Reopen a closed folio so a late charge or a correction can be posted to it. Opens the *bill* only: the stay stays departed and the room stays vacant, which is OPERA's split between Reopen Folio (post-departure, folio-only) and Reinstate (undo the checkout itself). Refuses a `void` folio, refuses a folio closed longer ago than the reopen window — a bill that can be reopened forever is not settled — and refuses a closed folio with no `closed_at`, since the window cannot be established without one. Re-applying to an already-open folio is a no-op. Closing again goes back through the ordinary zero-balance discipline.\n\nEffects: modify hospitality.folio.", "operationId": "apply_hospitality_action_reopen_folio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "note": { "title": "Free-text detail; required when `reason` is `other`", "type": "string" }, "reason": { "enum": [ "late_charge", "missed_posting", "billing_correction", "disputed_item", "payment_reversal", "other" ], "title": "Why the folio is being reopened", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.reopen_folio:apply" ] } ], "summary": "Reopen folio", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.reopen_folio/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_reopen_folio` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.reopen_folio:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_reopen_folio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "note": { "title": "Free-text detail; required when `reason` is `other`", "type": "string" }, "reason": { "enum": [ "late_charge", "missed_posting", "billing_correction", "disputed_item", "payment_reversal", "other" ], "title": "Why the folio is being reopened", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Reopen folio (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.reopen_folio/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_reopen_folio`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_reopen_folio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "note": { "title": "Free-text detail; required when `reason` is `other`", "type": "string" }, "reason": { "enum": [ "late_charge", "missed_posting", "billing_correction", "disputed_item", "payment_reversal", "other" ], "title": "Why the folio is being reopened", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Reopen folio (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.reopen_folio/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_reopen_folio` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.reopen_folio:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_reopen_folio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "note": { "title": "Free-text detail; required when `reason` is `other`", "type": "string" }, "reason": { "enum": [ "late_charge", "missed_posting", "billing_correction", "disputed_item", "payment_reversal", "other" ], "title": "Why the folio is being reopened", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Reopen folio (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.repoint_connector_mapping/apply": { "post": { "description": "Point one of a connector's streams at a different mapping definition version (`name@version`) — the `apaleo_charge@2` upgrade path, or a rollback to a prior version after a bad mapping ships. Upserts by mapping *name*: an existing entry for that name moves to the new version, and a name the connector does not yet carry is added, which is how a stream joins a live pipe. Explicit operator move, never implicit: in-flight runs are unaffected (each run pins its `mapping_ref` at start), previously rejected rows are retried under the new mapping on the next sync, and already-loaded rows are re-mapped only when their payload changes — re-processing history is a separate, deliberate backfill. Allowed while active or paused; refused on a retired connector. Emits `connector.mapping_repointed` with the from → to refs.\n\nEffects: modify hospitality.connector.", "operationId": "apply_hospitality_action_repoint_connector_mapping", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "mapping_ref": { "title": "Mapping definition reference to move to (name@version)", "type": "string" }, "reason": { "title": "Why the mapping is being re-pointed", "type": "string" } }, "required": [ "mapping_ref" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.connector" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.repoint_connector_mapping:apply" ] } ], "summary": "Re-point connector mapping", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.repoint_connector_mapping/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_repoint_connector_mapping` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.repoint_connector_mapping:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_repoint_connector_mapping", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "mapping_ref": { "title": "Mapping definition reference to move to (name@version)", "type": "string" }, "reason": { "title": "Why the mapping is being re-pointed", "type": "string" } }, "required": [ "mapping_ref" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.connector" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Re-point connector mapping (dry-run)", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.repoint_connector_mapping/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_repoint_connector_mapping`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_repoint_connector_mapping", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "mapping_ref": { "title": "Mapping definition reference to move to (name@version)", "type": "string" }, "reason": { "title": "Why the mapping is being re-pointed", "type": "string" } }, "required": [ "mapping_ref" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Re-point connector mapping (dry-run)", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.repoint_connector_mapping/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_repoint_connector_mapping` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.repoint_connector_mapping:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_repoint_connector_mapping", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "mapping_ref": { "title": "Mapping definition reference to move to (name@version)", "type": "string" }, "reason": { "title": "Why the mapping is being re-pointed", "type": "string" } }, "required": [ "mapping_ref" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Re-point connector mapping (rollup delta)", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.request_agent_installation/apply": { "post": { "description": "Propose an installation of a reviewed registry entry (marketplace-style request-then-approve, proposal 0020 §9.1). Runs the full enable-time validation pipeline but lands the installation at `installation_status = requested` with no activation stamps; an operator then activates it via `enable_agent_installation` with `installation_id`, or denies it via `suspend_agent_installation(new_status = revoked)`. Emits `agent_installation.requested`.\n\nEffects: create hospitality.agent_installation; link hospitality.link.agent_installation_for_registry_entry.", "operationId": "apply_hospitality_action_request_agent_installation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allowed_workflow_keys": { "items": { "type": "string" }, "title": "Optional workflow-key allowlist", "type": "array" }, "approval_policy": { "title": "Gates required for high-risk steps" }, "auth_mode": { "enum": [ "none", "oauth_client_credentials", "oauth_delegated", "api_key_reference", "jwt_exchange", "mcp_oauth" ], "title": "How the installation authenticates at call time", "type": "string" }, "credential_reference": { "title": "Opaque pointer into an external secret manager", "type": "string" }, "enabled_action_scopes": { "items": { "type": "string" }, "title": "Subset of registry entry declared action scopes", "type": "array" }, "enabled_data_classes": { "items": { "enum": [ "public", "operational", "guest_pii", "staff_pii", "payment_metadata", "regulated_health", "secrets" ], "type": "string" }, "title": "Subset of registry entry declared data classes", "type": "array" }, "enabled_function_scopes": { "items": { "type": "string" }, "title": "Subset of registry entry declared function scopes", "type": "array" }, "enabled_read_scopes": { "items": { "type": "string" }, "title": "Subset of registry entry declared read scopes; defaults to all of them", "type": "array" }, "enablement_note": { "title": "Free-text note", "type": "string" }, "expires_at": { "format": "date-time", "title": "Optional time-bound install", "type": "string" }, "installed_scope": { "enum": [ "tenant", "brand", "portfolio", "property", "venue" ], "title": "Tenancy scope this installation grants access at", "type": "string" }, "installed_scope_ref_object_id": { "title": "Required when installed_scope != tenant", "type": "string" }, "installed_scope_ref_object_type": { "title": "Required when installed_scope != tenant", "type": "string" } }, "required": [ "installed_scope", "auth_mode" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_registry_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.agent_installation_for_registry_entry" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.agent_installation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.request_agent_installation:apply" ] } ], "summary": "Request agent installation", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.request_agent_installation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_request_agent_installation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.request_agent_installation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_request_agent_installation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allowed_workflow_keys": { "items": { "type": "string" }, "title": "Optional workflow-key allowlist", "type": "array" }, "approval_policy": { "title": "Gates required for high-risk steps" }, "auth_mode": { "enum": [ "none", "oauth_client_credentials", "oauth_delegated", "api_key_reference", "jwt_exchange", "mcp_oauth" ], "title": "How the installation authenticates at call time", "type": "string" }, "credential_reference": { "title": "Opaque pointer into an external secret manager", "type": "string" }, "enabled_action_scopes": { "items": { "type": "string" }, "title": "Subset of registry entry declared action scopes", "type": "array" }, "enabled_data_classes": { "items": { "enum": [ "public", "operational", "guest_pii", "staff_pii", "payment_metadata", "regulated_health", "secrets" ], "type": "string" }, "title": "Subset of registry entry declared data classes", "type": "array" }, "enabled_function_scopes": { "items": { "type": "string" }, "title": "Subset of registry entry declared function scopes", "type": "array" }, "enabled_read_scopes": { "items": { "type": "string" }, "title": "Subset of registry entry declared read scopes; defaults to all of them", "type": "array" }, "enablement_note": { "title": "Free-text note", "type": "string" }, "expires_at": { "format": "date-time", "title": "Optional time-bound install", "type": "string" }, "installed_scope": { "enum": [ "tenant", "brand", "portfolio", "property", "venue" ], "title": "Tenancy scope this installation grants access at", "type": "string" }, "installed_scope_ref_object_id": { "title": "Required when installed_scope != tenant", "type": "string" }, "installed_scope_ref_object_type": { "title": "Required when installed_scope != tenant", "type": "string" } }, "required": [ "installed_scope", "auth_mode" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_registry_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.agent_installation_for_registry_entry" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.agent_installation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Request agent installation (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.request_agent_installation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_request_agent_installation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_request_agent_installation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allowed_workflow_keys": { "items": { "type": "string" }, "title": "Optional workflow-key allowlist", "type": "array" }, "approval_policy": { "title": "Gates required for high-risk steps" }, "auth_mode": { "enum": [ "none", "oauth_client_credentials", "oauth_delegated", "api_key_reference", "jwt_exchange", "mcp_oauth" ], "title": "How the installation authenticates at call time", "type": "string" }, "credential_reference": { "title": "Opaque pointer into an external secret manager", "type": "string" }, "enabled_action_scopes": { "items": { "type": "string" }, "title": "Subset of registry entry declared action scopes", "type": "array" }, "enabled_data_classes": { "items": { "enum": [ "public", "operational", "guest_pii", "staff_pii", "payment_metadata", "regulated_health", "secrets" ], "type": "string" }, "title": "Subset of registry entry declared data classes", "type": "array" }, "enabled_function_scopes": { "items": { "type": "string" }, "title": "Subset of registry entry declared function scopes", "type": "array" }, "enabled_read_scopes": { "items": { "type": "string" }, "title": "Subset of registry entry declared read scopes; defaults to all of them", "type": "array" }, "enablement_note": { "title": "Free-text note", "type": "string" }, "expires_at": { "format": "date-time", "title": "Optional time-bound install", "type": "string" }, "installed_scope": { "enum": [ "tenant", "brand", "portfolio", "property", "venue" ], "title": "Tenancy scope this installation grants access at", "type": "string" }, "installed_scope_ref_object_id": { "title": "Required when installed_scope != tenant", "type": "string" }, "installed_scope_ref_object_type": { "title": "Required when installed_scope != tenant", "type": "string" } }, "required": [ "installed_scope", "auth_mode" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_registry_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Request agent installation (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.request_agent_installation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_request_agent_installation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.request_agent_installation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_request_agent_installation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allowed_workflow_keys": { "items": { "type": "string" }, "title": "Optional workflow-key allowlist", "type": "array" }, "approval_policy": { "title": "Gates required for high-risk steps" }, "auth_mode": { "enum": [ "none", "oauth_client_credentials", "oauth_delegated", "api_key_reference", "jwt_exchange", "mcp_oauth" ], "title": "How the installation authenticates at call time", "type": "string" }, "credential_reference": { "title": "Opaque pointer into an external secret manager", "type": "string" }, "enabled_action_scopes": { "items": { "type": "string" }, "title": "Subset of registry entry declared action scopes", "type": "array" }, "enabled_data_classes": { "items": { "enum": [ "public", "operational", "guest_pii", "staff_pii", "payment_metadata", "regulated_health", "secrets" ], "type": "string" }, "title": "Subset of registry entry declared data classes", "type": "array" }, "enabled_function_scopes": { "items": { "type": "string" }, "title": "Subset of registry entry declared function scopes", "type": "array" }, "enabled_read_scopes": { "items": { "type": "string" }, "title": "Subset of registry entry declared read scopes; defaults to all of them", "type": "array" }, "enablement_note": { "title": "Free-text note", "type": "string" }, "expires_at": { "format": "date-time", "title": "Optional time-bound install", "type": "string" }, "installed_scope": { "enum": [ "tenant", "brand", "portfolio", "property", "venue" ], "title": "Tenancy scope this installation grants access at", "type": "string" }, "installed_scope_ref_object_id": { "title": "Required when installed_scope != tenant", "type": "string" }, "installed_scope_ref_object_type": { "title": "Required when installed_scope != tenant", "type": "string" } }, "required": [ "installed_scope", "auth_mode" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_registry_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Request agent installation (rollup delta)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.request_approval_gate/apply": { "post": { "description": "Open a durable `approval_gate` for a workflow step or for a standalone action. Inserts the gate in `requested` status (or `notified` when a `notification_target` is supplied), links it to the guarded step run when applicable, transitions the step to `waiting_for_approval`, and freezes the proposal §4.4.2 canonical context hash. Validators (commit 10): `approval_gate_eligible_decider` shape, `quorum_valid`, `agent_cannot_satisfy_human_gate` setup, expiry coherence.\n\nEffects: create hospitality.approval_gate; modify hospitality.workflow_step_run; link hospitality.link.approval_gate_for_workflow_step_run; link hospitality.link.approval_gate_for_federated_output; modify hospitality.workflow_run; link hospitality.link.approval_gate_for_automation; link hospitality.link.approval_gate_for_federated_analysis_definition; link hospitality.link.approval_gate_for_owner_statement; link hospitality.link.approval_gate_for_property_budget; link hospitality.link.approval_gate_for_purpose_grant.", "operationId": "apply_hospitality_action_request_approval_gate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "approval_strategy": { "enum": [ "any_one", "all", "quorum", "role_based", "ordered_chain", "separation_of_duties" ], "title": "How the gate combines decisions", "type": "string" }, "context_snapshot": { "title": "Frozen, redacted facts shown to approvers" }, "eligible_principal_ids": { "items": { "type": "string" }, "title": "Exact eligible principals (Principal::stable_id() shape)", "type": "array" }, "eligible_role_refs": { "items": { "type": "string" }, "title": "Staff roles / groups that may approve", "type": "array" }, "excluded_principal_ids": { "items": { "type": "string" }, "title": "Requesting agent / author / conflicted principals", "type": "array" }, "expires_at": { "format": "date-time", "title": "Gate timeout", "type": "string" }, "external_reference": { "title": "Slack ts, Linear issue id, PMS task id, email thread id, etc.", "type": "string" }, "gate_key": { "title": "Stable within the workflow run or action correlation id", "type": "string" }, "notification_target": { "enum": [ "in_product", "slack", "linear", "email", "pms_task", "webhook", "other" ], "title": "Where the gate notification surfaced", "type": "string" }, "required_approval_count": { "title": "Required for approval_strategy = quorum", "type": "integer" }, "risk_tier": { "enum": [ "read_only", "internal_write", "guest_message", "money_movement", "identity_or_fraud", "clinical_or_regulated", "other_high_risk" ], "title": "Risk tier of the guarded step / action", "type": "string" } }, "required": [ "gate_key", "approval_strategy", "context_snapshot", "risk_tier" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.approval_gate_for_workflow_step_run", "hospitality.link.approval_gate_for_federated_output", "hospitality.link.approval_gate_for_automation", "hospitality.link.approval_gate_for_federated_analysis_definition", "hospitality.link.approval_gate_for_owner_statement", "hospitality.link.approval_gate_for_property_budget", "hospitality.link.approval_gate_for_purpose_grant" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.approval_gate", "hospitality.workflow_step_run", "hospitality.workflow_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.request_approval_gate:apply" ] } ], "summary": "Request approval gate", "tags": [ "approvals" ] } }, "/v1/actions/hospitality.action.request_approval_gate/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_request_approval_gate` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.request_approval_gate:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_request_approval_gate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "approval_strategy": { "enum": [ "any_one", "all", "quorum", "role_based", "ordered_chain", "separation_of_duties" ], "title": "How the gate combines decisions", "type": "string" }, "context_snapshot": { "title": "Frozen, redacted facts shown to approvers" }, "eligible_principal_ids": { "items": { "type": "string" }, "title": "Exact eligible principals (Principal::stable_id() shape)", "type": "array" }, "eligible_role_refs": { "items": { "type": "string" }, "title": "Staff roles / groups that may approve", "type": "array" }, "excluded_principal_ids": { "items": { "type": "string" }, "title": "Requesting agent / author / conflicted principals", "type": "array" }, "expires_at": { "format": "date-time", "title": "Gate timeout", "type": "string" }, "external_reference": { "title": "Slack ts, Linear issue id, PMS task id, email thread id, etc.", "type": "string" }, "gate_key": { "title": "Stable within the workflow run or action correlation id", "type": "string" }, "notification_target": { "enum": [ "in_product", "slack", "linear", "email", "pms_task", "webhook", "other" ], "title": "Where the gate notification surfaced", "type": "string" }, "required_approval_count": { "title": "Required for approval_strategy = quorum", "type": "integer" }, "risk_tier": { "enum": [ "read_only", "internal_write", "guest_message", "money_movement", "identity_or_fraud", "clinical_or_regulated", "other_high_risk" ], "title": "Risk tier of the guarded step / action", "type": "string" } }, "required": [ "gate_key", "approval_strategy", "context_snapshot", "risk_tier" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.approval_gate_for_workflow_step_run", "hospitality.link.approval_gate_for_federated_output", "hospitality.link.approval_gate_for_automation", "hospitality.link.approval_gate_for_federated_analysis_definition", "hospitality.link.approval_gate_for_owner_statement", "hospitality.link.approval_gate_for_property_budget", "hospitality.link.approval_gate_for_purpose_grant" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.approval_gate", "hospitality.workflow_step_run", "hospitality.workflow_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Request approval gate (dry-run)", "tags": [ "approvals" ] } }, "/v1/actions/hospitality.action.request_approval_gate/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_request_approval_gate`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_request_approval_gate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "approval_strategy": { "enum": [ "any_one", "all", "quorum", "role_based", "ordered_chain", "separation_of_duties" ], "title": "How the gate combines decisions", "type": "string" }, "context_snapshot": { "title": "Frozen, redacted facts shown to approvers" }, "eligible_principal_ids": { "items": { "type": "string" }, "title": "Exact eligible principals (Principal::stable_id() shape)", "type": "array" }, "eligible_role_refs": { "items": { "type": "string" }, "title": "Staff roles / groups that may approve", "type": "array" }, "excluded_principal_ids": { "items": { "type": "string" }, "title": "Requesting agent / author / conflicted principals", "type": "array" }, "expires_at": { "format": "date-time", "title": "Gate timeout", "type": "string" }, "external_reference": { "title": "Slack ts, Linear issue id, PMS task id, email thread id, etc.", "type": "string" }, "gate_key": { "title": "Stable within the workflow run or action correlation id", "type": "string" }, "notification_target": { "enum": [ "in_product", "slack", "linear", "email", "pms_task", "webhook", "other" ], "title": "Where the gate notification surfaced", "type": "string" }, "required_approval_count": { "title": "Required for approval_strategy = quorum", "type": "integer" }, "risk_tier": { "enum": [ "read_only", "internal_write", "guest_message", "money_movement", "identity_or_fraud", "clinical_or_regulated", "other_high_risk" ], "title": "Risk tier of the guarded step / action", "type": "string" } }, "required": [ "gate_key", "approval_strategy", "context_snapshot", "risk_tier" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Request approval gate (dry-run)", "tags": [ "approvals" ] } }, "/v1/actions/hospitality.action.request_approval_gate/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_request_approval_gate` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.request_approval_gate:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_request_approval_gate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "approval_strategy": { "enum": [ "any_one", "all", "quorum", "role_based", "ordered_chain", "separation_of_duties" ], "title": "How the gate combines decisions", "type": "string" }, "context_snapshot": { "title": "Frozen, redacted facts shown to approvers" }, "eligible_principal_ids": { "items": { "type": "string" }, "title": "Exact eligible principals (Principal::stable_id() shape)", "type": "array" }, "eligible_role_refs": { "items": { "type": "string" }, "title": "Staff roles / groups that may approve", "type": "array" }, "excluded_principal_ids": { "items": { "type": "string" }, "title": "Requesting agent / author / conflicted principals", "type": "array" }, "expires_at": { "format": "date-time", "title": "Gate timeout", "type": "string" }, "external_reference": { "title": "Slack ts, Linear issue id, PMS task id, email thread id, etc.", "type": "string" }, "gate_key": { "title": "Stable within the workflow run or action correlation id", "type": "string" }, "notification_target": { "enum": [ "in_product", "slack", "linear", "email", "pms_task", "webhook", "other" ], "title": "Where the gate notification surfaced", "type": "string" }, "required_approval_count": { "title": "Required for approval_strategy = quorum", "type": "integer" }, "risk_tier": { "enum": [ "read_only", "internal_write", "guest_message", "money_movement", "identity_or_fraud", "clinical_or_regulated", "other_high_risk" ], "title": "Risk tier of the guarded step / action", "type": "string" } }, "required": [ "gate_key", "approval_strategy", "context_snapshot", "risk_tier" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Request approval gate (rollup delta)", "tags": [ "approvals" ] } }, "/v1/actions/hospitality.action.request_payment/apply": { "post": { "description": "Ask the guest for money against this booking (Mews's payment request): mints a `pending` payment request the card rail turns into a hosted pay link. `reason` defaults to `deposit` and `kind` to `payment`; `preauthorization` asks for a hold captured later through the authorise path. `amount` defaults, for a deposit or prepayment, to what the booking still owes (`deposit_required_amount` less `deposit_paid_amount`), and `expires_at` to the booking's `deposit_due_at`; one of each must resolve. Asking for a deposit when nothing is owed, or when a pending request for the same reason and kind already exists, changes nothing — so the booking automation can fire it on every new booking, and a re-delivered event asks once. A pending request is withdrawn by the booking it asks for: cancelling or no-showing the booking cancels it (`reservation_cancelled` / `no_show`), and a modification that re-derives the unpaid deposit cancels a deposit request (`deposit_changed`) without re-asking — the automation or the desk asks again for the new figure. Emits `payment_request.requested.recorded`.\n\nEffects: create hospitality.payment_request; link hospitality.link.payment_request_for_reservation; create hospitality.folio; link hospitality.link.reservation_has_folio.", "operationId": "apply_hospitality_action_request_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "What to ask for; defaults to the unpaid deposit", "type": "object" }, "expires_at": { "format": "date-time", "title": "When the request lapses; defaults to the deposit due date", "type": "string" }, "kind": { "enum": [ "payment", "preauthorization" ], "title": "payment (default) or preauthorization", "type": "string" }, "note": { "title": "What the guest reads beside the amount", "type": "string" }, "reason": { "enum": [ "deposit", "prepayment", "fee", "payment_card_missing", "payment_card_declined", "authentication_required" ], "title": "Why the house is asking (default deposit)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.payment_request_for_reservation", "hospitality.link.reservation_has_folio" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.payment_request", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.request_payment:apply" ] } ], "summary": "Request payment", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.request_payment/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_request_payment` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.request_payment:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_request_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "What to ask for; defaults to the unpaid deposit", "type": "object" }, "expires_at": { "format": "date-time", "title": "When the request lapses; defaults to the deposit due date", "type": "string" }, "kind": { "enum": [ "payment", "preauthorization" ], "title": "payment (default) or preauthorization", "type": "string" }, "note": { "title": "What the guest reads beside the amount", "type": "string" }, "reason": { "enum": [ "deposit", "prepayment", "fee", "payment_card_missing", "payment_card_declined", "authentication_required" ], "title": "Why the house is asking (default deposit)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.payment_request_for_reservation", "hospitality.link.reservation_has_folio" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.payment_request", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Request payment (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.request_payment/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_request_payment`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_request_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "What to ask for; defaults to the unpaid deposit", "type": "object" }, "expires_at": { "format": "date-time", "title": "When the request lapses; defaults to the deposit due date", "type": "string" }, "kind": { "enum": [ "payment", "preauthorization" ], "title": "payment (default) or preauthorization", "type": "string" }, "note": { "title": "What the guest reads beside the amount", "type": "string" }, "reason": { "enum": [ "deposit", "prepayment", "fee", "payment_card_missing", "payment_card_declined", "authentication_required" ], "title": "Why the house is asking (default deposit)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Request payment (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.request_payment/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_request_payment` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.request_payment:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_request_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "What to ask for; defaults to the unpaid deposit", "type": "object" }, "expires_at": { "format": "date-time", "title": "When the request lapses; defaults to the deposit due date", "type": "string" }, "kind": { "enum": [ "payment", "preauthorization" ], "title": "payment (default) or preauthorization", "type": "string" }, "note": { "title": "What the guest reads beside the amount", "type": "string" }, "reason": { "enum": [ "deposit", "prepayment", "fee", "payment_card_missing", "payment_card_declined", "authentication_required" ], "title": "Why the house is asking (default deposit)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Request payment (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.request_purpose_grant/apply": { "post": { "description": "Request a grant of an active `access_purpose` for a principal, with a recorded rationale — the PBAC apply-for-access step. Creates the `purpose_grant` in `requested`; approval rides the ordinary 0020 flow: call `request_approval_gate` targeting the grant (it implements the `approvable` interface) and the gate decision transitions it to `active` / `rejected`. `expires_at` is bounded by the purpose's `max_grant_hours`. Emits `purpose_grant.requested`.\n\nEffects: create hospitality.purpose_grant; link hospitality.link.purpose_grant_for_purpose.", "operationId": "apply_hospitality_action_request_purpose_grant", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "expires_at": { "format": "date-time", "title": "Requested lapse instant for the grant once active", "type": "string" }, "external_reference": { "title": "Opaque ref to the driving case", "type": "string" }, "principal_id": { "title": "Stable id of the principal the grant is for; defaults to the caller", "type": "string" }, "purpose": { "format": "uuid", "title": "The access_purpose to grant", "type": "string", "x-aerandil-references": "hospitality.access_purpose" }, "rationale_text": { "title": "Why this principal needs this purpose now (recorded verbatim)", "type": "string" } }, "required": [ "purpose", "rationale_text" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.purpose_grant_for_purpose" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.purpose_grant" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.request_purpose_grant:apply" ] } ], "summary": "Request purpose grant", "tags": [ "pbac" ] } }, "/v1/actions/hospitality.action.request_purpose_grant/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_request_purpose_grant` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.request_purpose_grant:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_request_purpose_grant", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "expires_at": { "format": "date-time", "title": "Requested lapse instant for the grant once active", "type": "string" }, "external_reference": { "title": "Opaque ref to the driving case", "type": "string" }, "principal_id": { "title": "Stable id of the principal the grant is for; defaults to the caller", "type": "string" }, "purpose": { "format": "uuid", "title": "The access_purpose to grant", "type": "string", "x-aerandil-references": "hospitality.access_purpose" }, "rationale_text": { "title": "Why this principal needs this purpose now (recorded verbatim)", "type": "string" } }, "required": [ "purpose", "rationale_text" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.purpose_grant_for_purpose" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.purpose_grant" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Request purpose grant (dry-run)", "tags": [ "pbac" ] } }, "/v1/actions/hospitality.action.request_purpose_grant/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_request_purpose_grant`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_request_purpose_grant", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "expires_at": { "format": "date-time", "title": "Requested lapse instant for the grant once active", "type": "string" }, "external_reference": { "title": "Opaque ref to the driving case", "type": "string" }, "principal_id": { "title": "Stable id of the principal the grant is for; defaults to the caller", "type": "string" }, "purpose": { "format": "uuid", "title": "The access_purpose to grant", "type": "string", "x-aerandil-references": "hospitality.access_purpose" }, "rationale_text": { "title": "Why this principal needs this purpose now (recorded verbatim)", "type": "string" } }, "required": [ "purpose", "rationale_text" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Request purpose grant (dry-run)", "tags": [ "pbac" ] } }, "/v1/actions/hospitality.action.request_purpose_grant/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_request_purpose_grant` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.request_purpose_grant:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_request_purpose_grant", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "expires_at": { "format": "date-time", "title": "Requested lapse instant for the grant once active", "type": "string" }, "external_reference": { "title": "Opaque ref to the driving case", "type": "string" }, "principal_id": { "title": "Stable id of the principal the grant is for; defaults to the caller", "type": "string" }, "purpose": { "format": "uuid", "title": "The access_purpose to grant", "type": "string", "x-aerandil-references": "hospitality.access_purpose" }, "rationale_text": { "title": "Why this principal needs this purpose now (recorded verbatim)", "type": "string" } }, "required": [ "purpose", "rationale_text" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Request purpose grant (rollup delta)", "tags": [ "pbac" ] } }, "/v1/actions/hospitality.action.reschedule_appointment/apply": { "post": { "description": "Move an appointment to a new start (duration preserved) and/or re-assign its room / provider. Re-runs the same conflict and capability checks as book_appointment against the new window and resources. Refused once the treatment has begun (in_service or later) — post-service corrections are an operator-surface repair, not a reschedule. Emits `spa.appointment_rescheduled`.\n\nEffects: modify hospitality.appointment; link hospitality.link.appointment_in_treatment_room; link hospitality.link.appointment_with_provider; unlink hospitality.link.appointment_in_treatment_room; unlink hospitality.link.appointment_with_provider.", "operationId": "apply_hospitality_action_reschedule_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "provider_id": { "format": "uuid", "title": "New provider (optional — omitted keeps the current assignment)", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "room_id": { "format": "uuid", "title": "New treatment room (optional — omitted keeps the current assignment)", "type": "string", "x-aerandil-references": "hospitality.treatment_room" }, "start_at": { "format": "date-time", "title": "New treatment start (end moves by the same duration)", "type": "string" } }, "required": [ "start_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.appointment_in_treatment_room", "hospitality.link.appointment_with_provider" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.appointment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.reschedule_appointment:apply" ] } ], "summary": "Reschedule appointment", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.reschedule_appointment/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_reschedule_appointment` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.reschedule_appointment:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_reschedule_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "provider_id": { "format": "uuid", "title": "New provider (optional — omitted keeps the current assignment)", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "room_id": { "format": "uuid", "title": "New treatment room (optional — omitted keeps the current assignment)", "type": "string", "x-aerandil-references": "hospitality.treatment_room" }, "start_at": { "format": "date-time", "title": "New treatment start (end moves by the same duration)", "type": "string" } }, "required": [ "start_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.appointment_in_treatment_room", "hospitality.link.appointment_with_provider" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.appointment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Reschedule appointment (dry-run)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.reschedule_appointment/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_reschedule_appointment`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_reschedule_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "provider_id": { "format": "uuid", "title": "New provider (optional — omitted keeps the current assignment)", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "room_id": { "format": "uuid", "title": "New treatment room (optional — omitted keeps the current assignment)", "type": "string", "x-aerandil-references": "hospitality.treatment_room" }, "start_at": { "format": "date-time", "title": "New treatment start (end moves by the same duration)", "type": "string" } }, "required": [ "start_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Reschedule appointment (dry-run)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.reschedule_appointment/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_reschedule_appointment` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.reschedule_appointment:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_reschedule_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "provider_id": { "format": "uuid", "title": "New provider (optional — omitted keeps the current assignment)", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "room_id": { "format": "uuid", "title": "New treatment room (optional — omitted keeps the current assignment)", "type": "string", "x-aerandil-references": "hospitality.treatment_room" }, "start_at": { "format": "date-time", "title": "New treatment start (end moves by the same duration)", "type": "string" } }, "required": [ "start_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Reschedule appointment (rollup delta)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.reschedule_function_event/apply": { "post": { "description": "Move an event: another day, another window, another space, another setup style — any subset. The diary and capacity checks run again over the result; a `do_not_move` event refuses a space change; an `actual` or `cancelled` event refuses outright. A window given without setup or teardown times drops the old ones.\n\nEffects: modify hospitality.function_event; unlink hospitality.link.function_event_in_space; link hospitality.link.function_event_in_space.", "operationId": "apply_hospitality_action_reschedule_function_event", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "end_at": { "format": "date-time", "title": "Doors close", "type": "string" }, "event_date": { "format": "date", "title": "The property-local day", "type": "string" }, "function_space_id": { "format": "uuid", "title": "The space to move it to", "type": "string", "x-aerandil-references": "hospitality.function_space" }, "setup_from": { "format": "date-time", "title": "When the setup crew may have the room", "type": "string" }, "setup_style": { "enum": [ "theatre", "classroom", "boardroom", "u_shape", "hollow_square", "banquet_rounds", "cabaret", "reception", "exhibition", "existing" ], "title": "How the room is set", "type": "string" }, "start_at": { "format": "date-time", "title": "Doors open", "type": "string" }, "teardown_until": { "format": "date-time", "title": "When the room must be clear again", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_event" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated", "linked" ] }, "link_type": { "enum": [ "hospitality.link.function_event_in_space" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.function_event" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.reschedule_function_event:apply" ] } ], "summary": "Reschedule function event", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.reschedule_function_event/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_reschedule_function_event` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.reschedule_function_event:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_reschedule_function_event", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "end_at": { "format": "date-time", "title": "Doors close", "type": "string" }, "event_date": { "format": "date", "title": "The property-local day", "type": "string" }, "function_space_id": { "format": "uuid", "title": "The space to move it to", "type": "string", "x-aerandil-references": "hospitality.function_space" }, "setup_from": { "format": "date-time", "title": "When the setup crew may have the room", "type": "string" }, "setup_style": { "enum": [ "theatre", "classroom", "boardroom", "u_shape", "hollow_square", "banquet_rounds", "cabaret", "reception", "exhibition", "existing" ], "title": "How the room is set", "type": "string" }, "start_at": { "format": "date-time", "title": "Doors open", "type": "string" }, "teardown_until": { "format": "date-time", "title": "When the room must be clear again", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_event" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated", "linked" ] }, "link_type": { "enum": [ "hospitality.link.function_event_in_space" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.function_event" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Reschedule function event (dry-run)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.reschedule_function_event/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_reschedule_function_event`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_reschedule_function_event", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "end_at": { "format": "date-time", "title": "Doors close", "type": "string" }, "event_date": { "format": "date", "title": "The property-local day", "type": "string" }, "function_space_id": { "format": "uuid", "title": "The space to move it to", "type": "string", "x-aerandil-references": "hospitality.function_space" }, "setup_from": { "format": "date-time", "title": "When the setup crew may have the room", "type": "string" }, "setup_style": { "enum": [ "theatre", "classroom", "boardroom", "u_shape", "hollow_square", "banquet_rounds", "cabaret", "reception", "exhibition", "existing" ], "title": "How the room is set", "type": "string" }, "start_at": { "format": "date-time", "title": "Doors open", "type": "string" }, "teardown_until": { "format": "date-time", "title": "When the room must be clear again", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_event" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Reschedule function event (dry-run)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.reschedule_function_event/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_reschedule_function_event` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.reschedule_function_event:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_reschedule_function_event", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "end_at": { "format": "date-time", "title": "Doors close", "type": "string" }, "event_date": { "format": "date", "title": "The property-local day", "type": "string" }, "function_space_id": { "format": "uuid", "title": "The space to move it to", "type": "string", "x-aerandil-references": "hospitality.function_space" }, "setup_from": { "format": "date-time", "title": "When the setup crew may have the room", "type": "string" }, "setup_style": { "enum": [ "theatre", "classroom", "boardroom", "u_shape", "hollow_square", "banquet_rounds", "cabaret", "reception", "exhibition", "existing" ], "title": "How the room is set", "type": "string" }, "start_at": { "format": "date-time", "title": "Doors open", "type": "string" }, "teardown_until": { "format": "date-time", "title": "When the room must be clear again", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_event" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Reschedule function event (rollup delta)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.resend_authentication_chase/apply": { "post": { "description": "Send a pending authentication's page to the guest again — the desk's Re-send. Whatever the house's chase rule, because the desk asked: by email, else SMS, under the same consent gate as `message_guest`'s service messages. Refused when the request is not a pending chase, the rail has not minted its page yet, the guest cannot be written to (the reason says why), or it was re-sent less than ten minutes ago (`chase_resent_recently`).\n\nEffects: modify hospitality.payment_request; create hospitality.guest_message; create hospitality.guest_conversation; modify hospitality.guest_conversation; link hospitality.link.guest_conversation_for_person; link hospitality.link.guest_conversation_at_property; link hospitality.link.guest_conversation_anchored_to_reservation; link hospitality.link.guest_message_in_conversation.", "operationId": "apply_hospitality_action_resend_authentication_chase", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment_request" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.guest_conversation_for_person", "hospitality.link.guest_conversation_at_property", "hospitality.link.guest_conversation_anchored_to_reservation", "hospitality.link.guest_message_in_conversation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.payment_request", "hospitality.guest_message", "hospitality.guest_conversation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.resend_authentication_chase:apply" ] } ], "summary": "Re-send authentication chase", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.resend_authentication_chase/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_resend_authentication_chase` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.resend_authentication_chase:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_resend_authentication_chase", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment_request" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.guest_conversation_for_person", "hospitality.link.guest_conversation_at_property", "hospitality.link.guest_conversation_anchored_to_reservation", "hospitality.link.guest_message_in_conversation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.payment_request", "hospitality.guest_message", "hospitality.guest_conversation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Re-send authentication chase (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.resend_authentication_chase/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_resend_authentication_chase`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_resend_authentication_chase", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment_request" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Re-send authentication chase (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.resend_authentication_chase/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_resend_authentication_chase` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.resend_authentication_chase:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_resend_authentication_chase", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment_request" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Re-send authentication chase (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.resolve_guest_feedback/apply": { "post": { "description": "Say what the house did about a complaint or a suggestion: the case goes `resolved` with the resolution and the time. Resolving it again with the same words is a no-op, with other words is refused; a closed case is refused, and so is a compliment — a compliment is closed, not resolved. Emits `guest_feedback.resolved`.\n\nEffects: modify hospitality.guest_feedback.", "operationId": "apply_hospitality_action_resolve_guest_feedback", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "resolution": { "title": "What the house did", "type": "string" } }, "required": [ "resolution" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.guest_feedback" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.resolve_guest_feedback:apply" ] } ], "summary": "Resolve guest feedback", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.resolve_guest_feedback/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_resolve_guest_feedback` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.resolve_guest_feedback:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_resolve_guest_feedback", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "resolution": { "title": "What the house did", "type": "string" } }, "required": [ "resolution" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.guest_feedback" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Resolve guest feedback (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.resolve_guest_feedback/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_resolve_guest_feedback`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_resolve_guest_feedback", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "resolution": { "title": "What the house did", "type": "string" } }, "required": [ "resolution" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Resolve guest feedback (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.resolve_guest_feedback/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_resolve_guest_feedback` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.resolve_guest_feedback:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_resolve_guest_feedback", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "resolution": { "title": "What the house did", "type": "string" } }, "required": [ "resolution" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Resolve guest feedback (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.resolve_payment_refund/apply": { "post": { "description": "Record the terminal outcome of a pending refund leg. Validators reject: target not a refund leg (payment_kind != refund), target not in status = pending, refund_status not in {refunded, failed, voided}, refund_status = failed without refund_failure_reason, refund_trace_reference_type / refund_trace_reference incoherence. Atomically transitions Payment.status = pending → refunded | failed | voided, sets refund_resolved_at, and updates psp_refund_reference / refund_trace_reference / refund_trace_reference_type / refund_failure_reason when provided. Failed / voided legs release refundable balance for retry per proposal 0019 §10.10 (retry creates a new leg with a new refund_correlation_id, never mutates the failed row back to pending).\n\nEffects: modify hospitality.payment; modify hospitality.folio; modify hospitality.reservation.", "operationId": "apply_hospitality_action_resolve_payment_refund", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "psp_refund_reference": { "title": "PSP-issued refund reference (set or update when not available at request time)", "type": "string" }, "refund_failure_reason": { "title": "PSP / network reason for failure (required for refund_status = failed)", "type": "string" }, "refund_resolved_at": { "format": "date-time", "title": "PSP-side outcome timestamp (defaults to now)", "type": "string" }, "refund_status": { "enum": [ "refunded", "failed", "voided" ], "title": "Terminal refund status: `refunded` (success), `failed` (PSP / network declined), `voided` (PSP-side refund cancellation before settlement)", "type": "string" }, "refund_trace_reference": { "title": "Network trace reference for cardholder-side traceability", "type": "string" }, "refund_trace_reference_type": { "enum": [ "arn", "stan", "rrn", "psp_generated", "unavailable" ], "title": "Type tag on refund_trace_reference", "type": "string" } }, "required": [ "refund_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.payment", "hospitality.folio", "hospitality.reservation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.resolve_payment_refund:apply" ] } ], "summary": "Resolve payment refund", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.resolve_payment_refund/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_resolve_payment_refund` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.resolve_payment_refund:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_resolve_payment_refund", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "psp_refund_reference": { "title": "PSP-issued refund reference (set or update when not available at request time)", "type": "string" }, "refund_failure_reason": { "title": "PSP / network reason for failure (required for refund_status = failed)", "type": "string" }, "refund_resolved_at": { "format": "date-time", "title": "PSP-side outcome timestamp (defaults to now)", "type": "string" }, "refund_status": { "enum": [ "refunded", "failed", "voided" ], "title": "Terminal refund status: `refunded` (success), `failed` (PSP / network declined), `voided` (PSP-side refund cancellation before settlement)", "type": "string" }, "refund_trace_reference": { "title": "Network trace reference for cardholder-side traceability", "type": "string" }, "refund_trace_reference_type": { "enum": [ "arn", "stan", "rrn", "psp_generated", "unavailable" ], "title": "Type tag on refund_trace_reference", "type": "string" } }, "required": [ "refund_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.payment", "hospitality.folio", "hospitality.reservation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Resolve payment refund (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.resolve_payment_refund/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_resolve_payment_refund`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_resolve_payment_refund", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "psp_refund_reference": { "title": "PSP-issued refund reference (set or update when not available at request time)", "type": "string" }, "refund_failure_reason": { "title": "PSP / network reason for failure (required for refund_status = failed)", "type": "string" }, "refund_resolved_at": { "format": "date-time", "title": "PSP-side outcome timestamp (defaults to now)", "type": "string" }, "refund_status": { "enum": [ "refunded", "failed", "voided" ], "title": "Terminal refund status: `refunded` (success), `failed` (PSP / network declined), `voided` (PSP-side refund cancellation before settlement)", "type": "string" }, "refund_trace_reference": { "title": "Network trace reference for cardholder-side traceability", "type": "string" }, "refund_trace_reference_type": { "enum": [ "arn", "stan", "rrn", "psp_generated", "unavailable" ], "title": "Type tag on refund_trace_reference", "type": "string" } }, "required": [ "refund_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Resolve payment refund (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.resolve_payment_refund/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_resolve_payment_refund` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.resolve_payment_refund:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_resolve_payment_refund", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "psp_refund_reference": { "title": "PSP-issued refund reference (set or update when not available at request time)", "type": "string" }, "refund_failure_reason": { "title": "PSP / network reason for failure (required for refund_status = failed)", "type": "string" }, "refund_resolved_at": { "format": "date-time", "title": "PSP-side outcome timestamp (defaults to now)", "type": "string" }, "refund_status": { "enum": [ "refunded", "failed", "voided" ], "title": "Terminal refund status: `refunded` (success), `failed` (PSP / network declined), `voided` (PSP-side refund cancellation before settlement)", "type": "string" }, "refund_trace_reference": { "title": "Network trace reference for cardholder-side traceability", "type": "string" }, "refund_trace_reference_type": { "enum": [ "arn", "stan", "rrn", "psp_generated", "unavailable" ], "title": "Type tag on refund_trace_reference", "type": "string" } }, "required": [ "refund_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Resolve payment refund (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.resolve_room_discrepancy/apply": { "post": { "description": "The front-desk verdict on a skip / sleep / person investigation: walk-out confirmed, unregistered occupant registered, observation error, or corrected by the front office. statuses_realigned is reserved for the system's own auto-resolution and refused here. Replaying the same verdict is a no-op; a closed investigation never changes its verdict.\n\nEffects: modify hospitality.room_discrepancy.", "operationId": "apply_hospitality_action_resolve_room_discrepancy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "notes": { "title": "Resolution notes", "type": "string" }, "outcome": { "enum": [ "statuses_realigned", "walkout_confirmed", "unregistered_occupant_registered", "observation_error", "corrected_by_front_office" ], "title": "What the investigation found", "type": "string" } }, "required": [ "outcome" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room_discrepancy" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.room_discrepancy" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.resolve_room_discrepancy:apply" ] } ], "summary": "Resolve room discrepancy", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.resolve_room_discrepancy/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_resolve_room_discrepancy` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.resolve_room_discrepancy:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_resolve_room_discrepancy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "notes": { "title": "Resolution notes", "type": "string" }, "outcome": { "enum": [ "statuses_realigned", "walkout_confirmed", "unregistered_occupant_registered", "observation_error", "corrected_by_front_office" ], "title": "What the investigation found", "type": "string" } }, "required": [ "outcome" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room_discrepancy" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.room_discrepancy" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Resolve room discrepancy (dry-run)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.resolve_room_discrepancy/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_resolve_room_discrepancy`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_resolve_room_discrepancy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "notes": { "title": "Resolution notes", "type": "string" }, "outcome": { "enum": [ "statuses_realigned", "walkout_confirmed", "unregistered_occupant_registered", "observation_error", "corrected_by_front_office" ], "title": "What the investigation found", "type": "string" } }, "required": [ "outcome" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room_discrepancy" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Resolve room discrepancy (dry-run)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.resolve_room_discrepancy/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_resolve_room_discrepancy` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.resolve_room_discrepancy:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_resolve_room_discrepancy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "notes": { "title": "Resolution notes", "type": "string" }, "outcome": { "enum": [ "statuses_realigned", "walkout_confirmed", "unregistered_occupant_registered", "observation_error", "corrected_by_front_office" ], "title": "What the investigation found", "type": "string" } }, "required": [ "outcome" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room_discrepancy" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Resolve room discrepancy (rollup delta)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.restate_channel_reservation/apply": { "post": { "description": "Apply a partner's modification to a booking we already hold. A modification is a full restatement on every wire — SiteMinder re-send the whole reservation, Mews re-send the whole group and treat omission as cancellation — so this takes the stay as the partner now states it and moves ours to match, through the same date-change the front desk uses. Committed upstream, like `apply_channel_reservation`: the guest has already been told they can stay the extra night, so the selling ceiling and the restriction wall stop being gates and become facts to record. That is the whole reason this is a verb rather than a call to `modify_reservation_dates` — routing a channel restatement through the gated path would silently refuse exactly the extensions that matter, and leave the house expecting a guest to leave on a day the OTA has already sold them. Any breach lands on `availability_day.committed_oversell` and is reported on the delivery as `oversold_by`. Separate from `apply_channel_reservation` because the required sets differ: a restatement names the reservation it restates *and* the stay, where a booking names only the stay. A restatement that matches what we already hold is a no-op — which is the commonest case on a wire that re-sends everything. Restating the room type is not served here: a mid-stay room swap is a different unwind (see `docs/deferred.md`). Emits `channel_reservation.applied`.\n\nEffects: modify hospitality.channel_reservation_delivery; link hospitality.link.reservation_delivery_produced_reservation; modify hospitality.reservation; modify hospitality.reservation_room; modify hospitality.availability_day; create hospitality.reservation_night; modify hospitality.reservation_night; delete hospitality.reservation_night; link hospitality.link.reservation_room_has_night; link hospitality.link.reservation_night_uses_rate_plan; modify hospitality.payment_request.\n\nStep-up when `pricing_policy` is `override`: a person (a `User` principal) needs a fresh desk step-up proof — Pricing nights at a typed-in rate overrides the house's published price — or the call is refused `403 step_up_required` before anything runs. Re-enter the passcode at `POST /v1/desk/sessions/{id}/passcode` and retry. Machine principals are not gated.", "operationId": "apply_hospitality_action_restate_channel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "new_arrival_date": { "format": "date", "title": "Arrival date as the partner now states it", "type": "string" }, "new_departure_date": { "format": "date", "title": "Departure date as the partner now states it", "type": "string" }, "override_nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate for pricing_policy = override", "type": "object" }, "override_reason": { "title": "Why the override price (required with pricing_policy = override)", "type": "string" }, "pricing_policy": { "enum": [ "keep_rate", "requote", "requote_added_nights_only", "override" ], "title": "How affected nights re-price (required; never silent)", "type": "string" }, "reservation_id": { "format": "uuid", "title": "The reservation the partner restated", "type": "string", "x-aerandil-references": "hospitality.reservation" } }, "required": [ "reservation_id", "new_arrival_date", "new_departure_date", "pricing_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_reservation_delivery" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.reservation_delivery_produced_reservation", "hospitality.link.reservation_room_has_night", "hospitality.link.reservation_night_uses_rate_plan" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created", "deleted" ] }, "object_type": { "enum": [ "hospitality.channel_reservation_delivery", "hospitality.reservation", "hospitality.reservation_room", "hospitality.availability_day", "hospitality.reservation_night", "hospitality.payment_request" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "403": { "description": "`step_up_required` — a person applied this without a fresh desk step-up proof; nothing ran." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.restate_channel_reservation:apply" ] } ], "summary": "Restate channel reservation", "tags": [ "channel_manager" ], "x-aerandil-step-up": { "reason": "Pricing nights at a typed-in rate overrides the house's published price", "when": { "kind": "param_equals", "param": "pricing_policy", "value": "override" } } } }, "/v1/actions/hospitality.action.restate_channel_reservation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_restate_channel_reservation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.restate_channel_reservation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_restate_channel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "new_arrival_date": { "format": "date", "title": "Arrival date as the partner now states it", "type": "string" }, "new_departure_date": { "format": "date", "title": "Departure date as the partner now states it", "type": "string" }, "override_nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate for pricing_policy = override", "type": "object" }, "override_reason": { "title": "Why the override price (required with pricing_policy = override)", "type": "string" }, "pricing_policy": { "enum": [ "keep_rate", "requote", "requote_added_nights_only", "override" ], "title": "How affected nights re-price (required; never silent)", "type": "string" }, "reservation_id": { "format": "uuid", "title": "The reservation the partner restated", "type": "string", "x-aerandil-references": "hospitality.reservation" } }, "required": [ "reservation_id", "new_arrival_date", "new_departure_date", "pricing_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_reservation_delivery" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.reservation_delivery_produced_reservation", "hospitality.link.reservation_room_has_night", "hospitality.link.reservation_night_uses_rate_plan" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created", "deleted" ] }, "object_type": { "enum": [ "hospitality.channel_reservation_delivery", "hospitality.reservation", "hospitality.reservation_room", "hospitality.availability_day", "hospitality.reservation_night", "hospitality.payment_request" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Restate channel reservation (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.restate_channel_reservation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_restate_channel_reservation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_restate_channel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "new_arrival_date": { "format": "date", "title": "Arrival date as the partner now states it", "type": "string" }, "new_departure_date": { "format": "date", "title": "Departure date as the partner now states it", "type": "string" }, "override_nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate for pricing_policy = override", "type": "object" }, "override_reason": { "title": "Why the override price (required with pricing_policy = override)", "type": "string" }, "pricing_policy": { "enum": [ "keep_rate", "requote", "requote_added_nights_only", "override" ], "title": "How affected nights re-price (required; never silent)", "type": "string" }, "reservation_id": { "format": "uuid", "title": "The reservation the partner restated", "type": "string", "x-aerandil-references": "hospitality.reservation" } }, "required": [ "reservation_id", "new_arrival_date", "new_departure_date", "pricing_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_reservation_delivery" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Restate channel reservation (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.restate_channel_reservation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_restate_channel_reservation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.restate_channel_reservation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_restate_channel_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "new_arrival_date": { "format": "date", "title": "Arrival date as the partner now states it", "type": "string" }, "new_departure_date": { "format": "date", "title": "Departure date as the partner now states it", "type": "string" }, "override_nightly_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Nightly rate for pricing_policy = override", "type": "object" }, "override_reason": { "title": "Why the override price (required with pricing_policy = override)", "type": "string" }, "pricing_policy": { "enum": [ "keep_rate", "requote", "requote_added_nights_only", "override" ], "title": "How affected nights re-price (required; never silent)", "type": "string" }, "reservation_id": { "format": "uuid", "title": "The reservation the partner restated", "type": "string", "x-aerandil-references": "hospitality.reservation" } }, "required": [ "reservation_id", "new_arrival_date", "new_departure_date", "pricing_policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_reservation_delivery" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Restate channel reservation (rollup delta)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.resume_channel_connection/apply": { "post": { "description": "Return a paused or suspended conduit to `active`. Resuming does not itself publish anything: the dispatcher's next pass picks up whatever accumulated in the outbox while the conduit was stopped, which is why a long pause is followed by a large delta rather than a full flush. Emits `channel_connection.resumed`.\n\nEffects: modify hospitality.channel_connection.", "operationId": "apply_hospitality_action_resume_channel_connection", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.channel_connection" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.resume_channel_connection:apply" ] } ], "summary": "Resume channel connection", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.resume_channel_connection/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_resume_channel_connection` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.resume_channel_connection:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_resume_channel_connection", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.channel_connection" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Resume channel connection (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.resume_channel_connection/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_resume_channel_connection`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_resume_channel_connection", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Resume channel connection (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.resume_channel_connection/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_resume_channel_connection` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.resume_channel_connection:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_resume_channel_connection", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Resume channel connection (rollup delta)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.resume_connector/apply": { "post": { "description": "Resume a `paused` connector — clears `paused_reason` and returns it to `active` so the worker schedules syncs again. Emits `connector.resumed`.\n\nEffects: modify hospitality.connector.", "operationId": "apply_hospitality_action_resume_connector", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.connector" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.resume_connector:apply" ] } ], "summary": "Resume connector", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.resume_connector/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_resume_connector` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.resume_connector:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_resume_connector", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.connector" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Resume connector (dry-run)", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.resume_connector/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_resume_connector`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_resume_connector", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Resume connector (dry-run)", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.resume_connector/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_resume_connector` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.resume_connector:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_resume_connector", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Resume connector (rollup delta)", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.resume_work_order/apply": { "post": { "description": "Bring a postponed work order back onto the board: postponed → open, clearing postponed_until, postponed_until_at and postpone_reason (and a scheduled_for the postponement overtook), and writing a `note` line on its thread that says it came back and from which date, in the same transaction. The standing automation `ops_automations::postponed_work_order_resume` fires it when the house's day reaches the date (postponed_until_at); an engineer may bring one back early. Refused on an order that is not postponed — so a second firing, or a replay after the order moved on, changes nothing. Emits `work_order.resumed`.\n\nEffects: modify hospitality.work_order; create hospitality.work_order_entry; link hospitality.link.work_order_entry_for_work_order; link hospitality.link.work_order_entry_recorded_by.", "operationId": "apply_hospitality_action_resume_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.work_order_entry_for_work_order", "hospitality.link.work_order_entry_recorded_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.work_order", "hospitality.work_order_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.resume_work_order:apply" ] } ], "summary": "Resume work order", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.resume_work_order/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_resume_work_order` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.resume_work_order:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_resume_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.work_order_entry_for_work_order", "hospitality.link.work_order_entry_recorded_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.work_order", "hospitality.work_order_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Resume work order (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.resume_work_order/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_resume_work_order`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_resume_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Resume work order (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.resume_work_order/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_resume_work_order` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.resume_work_order:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_resume_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Resume work order (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retime_housekeeping_task/apply": { "post": { "description": "Move a request's due time — the desk's \"make it four, not three\". Open work only (pending, in progress or blocked); a finished or skipped task keeps its time. The new `due_at` is held to the house's day as on creation (no earlier than the start of the day before the house's today), and a pending task whose new time falls on another day moves to that day's sheet (`business_date`); a started one keeps its day. A time still to come clears an `overdue_at` the sweep had stamped, so the request can turn overdue again. The same time again is a no-op. Emits `housekeeping.task.retimed` with the old and new times.\n\nEffects: modify hospitality.housekeeping_task.", "operationId": "apply_hospitality_action_retime_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "due_at": { "format": "date-time", "title": "The new due time", "type": "string" }, "reason": { "title": "Why it moved (carried on the event; never on the task)", "type": "string" } }, "required": [ "due_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.retime_housekeeping_task:apply" ] } ], "summary": "Retime housekeeping task", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retime_housekeeping_task/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_retime_housekeeping_task` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.retime_housekeeping_task:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_retime_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "due_at": { "format": "date-time", "title": "The new due time", "type": "string" }, "reason": { "title": "Why it moved (carried on the event; never on the task)", "type": "string" } }, "required": [ "due_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Retime housekeeping task (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retime_housekeeping_task/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_retime_housekeeping_task`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_retime_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "due_at": { "format": "date-time", "title": "The new due time", "type": "string" }, "reason": { "title": "Why it moved (carried on the event; never on the task)", "type": "string" } }, "required": [ "due_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Retime housekeeping task (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retime_housekeeping_task/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_retime_housekeeping_task` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.retime_housekeeping_task:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_retime_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "due_at": { "format": "date-time", "title": "The new due time", "type": "string" }, "reason": { "title": "Why it moved (carried on the event; never on the task)", "type": "string" } }, "required": [ "due_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Retime housekeeping task (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_access_purpose/apply": { "post": { "description": "Retire an `access_purpose`: no new grants, no enforcement gating from it, audit trail kept. Existing active grants keep running until they expire or are revoked — retirement changes what can be granted, not what was. Idempotent on a retired purpose. Emits `access_purpose.retired`.\n\nEffects: modify hospitality.access_purpose.", "operationId": "apply_hospitality_action_retire_access_purpose", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the purpose is being retired", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.access_purpose" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.access_purpose" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.retire_access_purpose:apply" ] } ], "summary": "Retire access purpose", "tags": [ "pbac" ] } }, "/v1/actions/hospitality.action.retire_access_purpose/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_retire_access_purpose` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.retire_access_purpose:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_retire_access_purpose", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the purpose is being retired", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.access_purpose" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.access_purpose" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Retire access purpose (dry-run)", "tags": [ "pbac" ] } }, "/v1/actions/hospitality.action.retire_access_purpose/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_retire_access_purpose`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_retire_access_purpose", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the purpose is being retired", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.access_purpose" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Retire access purpose (dry-run)", "tags": [ "pbac" ] } }, "/v1/actions/hospitality.action.retire_access_purpose/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_retire_access_purpose` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.retire_access_purpose:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_retire_access_purpose", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the purpose is being retired", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.access_purpose" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Retire access purpose (rollup delta)", "tags": [ "pbac" ] } }, "/v1/actions/hospitality.action.retire_agent_eval_case/apply": { "post": { "description": "Take a promoted eval case out of the agent's effective suite (`status = retired`) — the off-ramp for a mistaken promotion or a case whose subject went stale. Retired, not deleted: the provenance trail back to the source trace survives, and retiring an already-retired case is an idempotent no-op. Emits `agent_eval_case.retired`.\n\nEffects: modify hospitality.agent_eval_case.", "operationId": "apply_hospitality_action_retire_agent_eval_case", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the case is retired", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_eval_case" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.agent_eval_case" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.retire_agent_eval_case:apply" ] } ], "summary": "Retire agent eval case", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.retire_agent_eval_case/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_retire_agent_eval_case` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.retire_agent_eval_case:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_retire_agent_eval_case", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the case is retired", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_eval_case" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.agent_eval_case" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Retire agent eval case (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.retire_agent_eval_case/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_retire_agent_eval_case`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_retire_agent_eval_case", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the case is retired", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_eval_case" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Retire agent eval case (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.retire_agent_eval_case/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_retire_agent_eval_case` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.retire_agent_eval_case:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_retire_agent_eval_case", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the case is retired", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_eval_case" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Retire agent eval case (rollup delta)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.retire_asset/apply": { "post": { "description": "The equipment is gone — removed, replaced, scrapped. Terminal: stamps retired_at and the reason, and retires every preventive plan that looks after it in the same transaction (a plan for a boiler that is no longer there raises nothing more). Work orders already open for it stay open — the order that replaces it may be one of them. Its code stays taken. Retiring a retired asset is a no-op.\n\nEffects: modify hospitality.asset; modify hospitality.maintenance_plan.", "operationId": "apply_hospitality_action_retire_asset", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the asset is retired", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.asset" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.asset", "hospitality.maintenance_plan" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.retire_asset:apply" ] } ], "summary": "Retire asset", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_asset/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_retire_asset` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.retire_asset:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_retire_asset", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the asset is retired", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.asset" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.asset", "hospitality.maintenance_plan" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Retire asset (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_asset/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_retire_asset`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_retire_asset", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the asset is retired", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.asset" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Retire asset (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_asset/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_retire_asset` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.retire_asset:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_retire_asset", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the asset is retired", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.asset" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Retire asset (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_board_sort_pattern/apply": { "post": { "description": "Give a board back to the kernel's default order: the pattern stops ordering it (`board_sort` reads the default, or a staff member's own preference). Retiring a retired pattern is a no-op; set_board_sort_pattern for the same board revives it. Emits `board_sort_pattern.retired`.\n\nEffects: modify hospitality.board_sort_pattern.", "operationId": "apply_hospitality_action_retire_board_sort_pattern", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.board_sort_pattern" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.board_sort_pattern" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.retire_board_sort_pattern:apply" ] } ], "summary": "Retire board sort pattern", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_board_sort_pattern/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_retire_board_sort_pattern` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.retire_board_sort_pattern:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_retire_board_sort_pattern", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.board_sort_pattern" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.board_sort_pattern" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Retire board sort pattern (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_board_sort_pattern/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_retire_board_sort_pattern`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_retire_board_sort_pattern", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.board_sort_pattern" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Retire board sort pattern (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_board_sort_pattern/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_retire_board_sort_pattern` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.retire_board_sort_pattern:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_retire_board_sort_pattern", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.board_sort_pattern" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Retire board sort pattern (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_checklist_template/apply": { "post": { "description": "Stop a checklist template resolving onto tasks — and so stop it gating their completion. Results already recorded against it stay. Retiring a retired template is a no-op. Emits `checklist_template.retired`.\n\nEffects: modify hospitality.checklist_template.", "operationId": "apply_hospitality_action_retire_checklist_template", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.checklist_template" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.checklist_template" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.retire_checklist_template:apply" ] } ], "summary": "Retire checklist template", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_checklist_template/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_retire_checklist_template` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.retire_checklist_template:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_retire_checklist_template", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.checklist_template" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.checklist_template" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Retire checklist template (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_checklist_template/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_retire_checklist_template`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_retire_checklist_template", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.checklist_template" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Retire checklist template (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_checklist_template/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_retire_checklist_template` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.retire_checklist_template:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_retire_checklist_template", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.checklist_template" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Retire checklist template (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_connector/apply": { "post": { "description": "Retire a connector — terminal; the property stopped using the source system. The row and its sync-run history stay (soft-delete is the ontology-wide contract; lineage on imported objects keeps pointing here). Emits `connector.retired`.\n\nEffects: modify hospitality.connector.", "operationId": "apply_hospitality_action_retire_connector", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the connector is being retired", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.connector" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.retire_connector:apply" ] } ], "summary": "Retire connector", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.retire_connector/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_retire_connector` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.retire_connector:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_retire_connector", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the connector is being retired", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.connector" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Retire connector (dry-run)", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.retire_connector/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_retire_connector`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_retire_connector", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the connector is being retired", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Retire connector (dry-run)", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.retire_connector/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_retire_connector` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.retire_connector:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_retire_connector", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the connector is being retired", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Retire connector (rollup delta)", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.retire_fault_type/apply": { "post": { "description": "Take a fault type out of its catalogue for good. Stamps retired_at and the reason; its code stays taken. No new order is raised from it; orders already raised keep their words and their edge to it. Retiring a retired fault type is a no-op. Emits `fault_type.retired`.\n\nEffects: modify hospitality.fault_type.", "operationId": "apply_hospitality_action_retire_fault_type", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why it is retired", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fault_type" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.fault_type" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.retire_fault_type:apply" ] } ], "summary": "Retire fault type", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_fault_type/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_retire_fault_type` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.retire_fault_type:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_retire_fault_type", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why it is retired", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fault_type" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.fault_type" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Retire fault type (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_fault_type/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_retire_fault_type`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_retire_fault_type", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why it is retired", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fault_type" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Retire fault type (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_fault_type/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_retire_fault_type` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.retire_fault_type:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_retire_fault_type", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why it is retired", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fault_type" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Retire fault type (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_grounding_scope/apply": { "post": { "description": "Retire a `grounding_scope`: it stops feeding the retrieval context but stays referenceable for audit. Retiring an already-retired scope is rejected. Emits `grounding_scope.retired`.\n\nEffects: modify hospitality.grounding_scope.", "operationId": "apply_hospitality_action_retire_grounding_scope", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.grounding_scope" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.grounding_scope" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.retire_grounding_scope:apply" ] } ], "summary": "Retire grounding scope", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.retire_grounding_scope/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_retire_grounding_scope` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.retire_grounding_scope:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_retire_grounding_scope", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.grounding_scope" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.grounding_scope" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Retire grounding scope (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.retire_grounding_scope/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_retire_grounding_scope`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_retire_grounding_scope", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.grounding_scope" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Retire grounding scope (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.retire_grounding_scope/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_retire_grounding_scope` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.retire_grounding_scope:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_retire_grounding_scope", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.grounding_scope" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Retire grounding scope (rollup delta)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.retire_housekeeping_credit_rule/apply": { "post": { "description": "Stop a housekeeping credit rule pricing new tasks. Tasks it already priced keep their credits; a room-type rule's task type falls back to the house's rule for every room type, if there is one. Retiring a retired rule is a no-op; authoring its key again (`set_housekeeping_credit_rule`) revives it. Emits `housekeeping_credit_rule.retired`.\n\nEffects: modify hospitality.housekeeping_credit_rule.", "operationId": "apply_hospitality_action_retire_housekeeping_credit_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_credit_rule" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.housekeeping_credit_rule" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.retire_housekeeping_credit_rule:apply" ] } ], "summary": "Retire housekeeping credit rule", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_housekeeping_credit_rule/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_retire_housekeeping_credit_rule` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.retire_housekeeping_credit_rule:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_retire_housekeeping_credit_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_credit_rule" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.housekeeping_credit_rule" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Retire housekeeping credit rule (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_housekeeping_credit_rule/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_retire_housekeeping_credit_rule`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_retire_housekeeping_credit_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_credit_rule" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Retire housekeeping credit rule (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_housekeeping_credit_rule/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_retire_housekeeping_credit_rule` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.retire_housekeeping_credit_rule:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_retire_housekeeping_credit_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_credit_rule" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Retire housekeeping credit rule (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_maintenance_plan/apply": { "post": { "description": "Stop a plan: it raises nothing more. An order it already raised stays open for the engineer to finish or void. Retiring a retired plan is a no-op.\n\nEffects: modify hospitality.maintenance_plan.", "operationId": "apply_hospitality_action_retire_maintenance_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.maintenance_plan" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.maintenance_plan" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.retire_maintenance_plan:apply" ] } ], "summary": "Retire maintenance plan", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_maintenance_plan/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_retire_maintenance_plan` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.retire_maintenance_plan:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_retire_maintenance_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.maintenance_plan" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.maintenance_plan" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Retire maintenance plan (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_maintenance_plan/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_retire_maintenance_plan`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_retire_maintenance_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.maintenance_plan" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Retire maintenance plan (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_maintenance_plan/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_retire_maintenance_plan` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.retire_maintenance_plan:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_retire_maintenance_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.maintenance_plan" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Retire maintenance plan (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_material/apply": { "post": { "description": "Take a material out of the catalogue for good — discontinued, replaced. Stamps retired_at and the reason; its code stays taken. Nothing more of it is received; what the stores still hold may be issued, consumed and counted down. Retiring a retired material is a no-op. Retired by the role whose family it is (2026-10-17): an engineer's session the spare parts and consumables, a housekeeping supervisor's the rest (403).\n\nEffects: modify hospitality.material.", "operationId": "apply_hospitality_action_retire_material", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why it is retired", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.material" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.material" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.retire_material:apply" ] } ], "summary": "Retire material", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_material/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_retire_material` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.retire_material:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_retire_material", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why it is retired", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.material" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.material" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Retire material (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_material/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_retire_material`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_retire_material", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why it is retired", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.material" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Retire material (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_material/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_retire_material` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.retire_material:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_retire_material", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why it is retired", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.material" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Retire material (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_payment_card/apply": { "post": { "description": "Take a card out of use: `active → removed` when the guest asks or the desk withdraws it, `active → expired` when it simply aged out. Never a deletion — a card that backed a settled payment is chargeback evidence, and `payment_drawn_on_card` has to keep pointing at something. Forgetting the record is the retention clock's job. Validators reject a card that is already terminal.\n\nEffects: modify hospitality.payment_card.", "operationId": "apply_hospitality_action_retire_payment_card", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "card_status": { "enum": [ "removed", "expired" ], "title": "Terminal state: `removed` (withdrawn) or `expired` (aged out)", "type": "string" } }, "required": [ "card_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment_card" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.payment_card" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.retire_payment_card:apply" ] } ], "summary": "Retire payment card", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.retire_payment_card/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_retire_payment_card` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.retire_payment_card:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_retire_payment_card", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "card_status": { "enum": [ "removed", "expired" ], "title": "Terminal state: `removed` (withdrawn) or `expired` (aged out)", "type": "string" } }, "required": [ "card_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment_card" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.payment_card" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Retire payment card (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.retire_payment_card/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_retire_payment_card`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_retire_payment_card", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "card_status": { "enum": [ "removed", "expired" ], "title": "Terminal state: `removed` (withdrawn) or `expired` (aged out)", "type": "string" } }, "required": [ "card_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment_card" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Retire payment card (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.retire_payment_card/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_retire_payment_card` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.retire_payment_card:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_retire_payment_card", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "card_status": { "enum": [ "removed", "expired" ], "title": "Terminal state: `removed` (withdrawn) or `expired` (aged out)", "type": "string" } }, "required": [ "card_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment_card" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Retire payment card (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.retire_public_area/apply": { "post": { "description": "Retire a public area — closed for the season, walled off in a refit. It gets no more daily cleans, and its reader code is cleared, so a scan opens nothing and the code is free for another place. Its open generated tasks (pending or blocked) are skipped with the reason recorded, as the generator retires work the state no longer calls for; work under way, finished work and hand-minted tasks are left alone. Retiring a retired area is a no-op; `register_public_area` with its code revives it. Emits `public_area.retired`.\n\nEffects: modify hospitality.public_area; modify hospitality.housekeeping_task.", "operationId": "apply_hospitality_action_retire_public_area", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.public_area" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.public_area", "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.retire_public_area:apply" ] } ], "summary": "Retire public area", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_public_area/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_retire_public_area` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.retire_public_area:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_retire_public_area", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.public_area" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.public_area", "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Retire public area (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_public_area/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_retire_public_area`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_retire_public_area", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.public_area" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Retire public area (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_public_area/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_retire_public_area` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.retire_public_area:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_retire_public_area", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.public_area" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Retire public area (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_round_template/apply": { "post": { "description": "Stop a round template falling due: the sweep starts no more rounds of it, and its name is free for a new template. A round already under way stays open for its walker to complete or cancel. Retiring a retired template is a no-op. Emits `round_template.retired`.\n\nEffects: modify hospitality.round_template.", "operationId": "apply_hospitality_action_retire_round_template", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.round_template" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.round_template" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.retire_round_template:apply" ] } ], "summary": "Retire round template", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_round_template/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_retire_round_template` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.retire_round_template:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_retire_round_template", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.round_template" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.round_template" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Retire round template (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_round_template/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_retire_round_template`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_retire_round_template", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.round_template" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Retire round template (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_round_template/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_retire_round_template` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.retire_round_template:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_retire_round_template", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.round_template" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Retire round template (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_worker_group/apply": { "post": { "description": "Retire a worker group: it takes no more work, and its open work — housekeeping tasks not complete or skipped, work orders not complete or void — goes back to the open board, unassigned, so nothing is left waiting on a group nobody works in. Its membership is kept as history. Retiring a retired group is a no-op; `define_worker_group` with its name revives it. Emits `worker_group.retired` naming the work it released.\n\nEffects: modify hospitality.worker_group; unlink hospitality.link.housekeeping_task_assigned_to_group; unlink hospitality.link.work_order_assigned_to_group; modify hospitality.work_order; modify hospitality.housekeeping_task.", "operationId": "apply_hospitality_action_retire_worker_group", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.worker_group" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.housekeeping_task_assigned_to_group", "hospitality.link.work_order_assigned_to_group" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.worker_group", "hospitality.work_order", "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.retire_worker_group:apply" ] } ], "summary": "Retire worker group", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_worker_group/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_retire_worker_group` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.retire_worker_group:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_retire_worker_group", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.worker_group" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.housekeeping_task_assigned_to_group", "hospitality.link.work_order_assigned_to_group" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.worker_group", "hospitality.work_order", "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Retire worker group (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_worker_group/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_retire_worker_group`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_retire_worker_group", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.worker_group" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Retire worker group (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retire_worker_group/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_retire_worker_group` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.retire_worker_group:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_retire_worker_group", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.worker_group" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Retire worker group (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.retrain_shard/apply": { "post": { "description": "Record that a SISA shard is being retrained as unlearning (proposal 0026 §4 step 5). Thin emitter — the retraining orchestration is a 2027 FL proposal (§6) — that emits `model.shard_retrained` naming the shard, the model, and the `revoked_at`-driven reason. The typical trigger is the revocation sweep finding a revoked record in a shard's membership; the follow-on `publish_model_version` registers the bumped version.", "operationId": "apply_hospitality_action_retrain_shard", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "model_name": { "title": "Model whose shard is retrained (ApiName form)", "type": "string" }, "prior_model_version": { "title": "The model version this retrain supersedes", "type": "integer" }, "reason": { "title": "Operator-facing reason for the retrain (audit metadata)", "type": "string" }, "shard_id": { "title": "SISA shard id being retrained", "type": "integer" }, "triggering_revocation_event_seq": { "title": "events.seq of the consent.revoked event that triggered this retrain, when applicable", "type": "integer" } }, "required": [ "model_name", "shard_id", "prior_model_version" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.retrain_shard:apply" ] } ], "summary": "Retrain shard", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.retrain_shard/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_retrain_shard` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.retrain_shard:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_retrain_shard", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "model_name": { "title": "Model whose shard is retrained (ApiName form)", "type": "string" }, "prior_model_version": { "title": "The model version this retrain supersedes", "type": "integer" }, "reason": { "title": "Operator-facing reason for the retrain (audit metadata)", "type": "string" }, "shard_id": { "title": "SISA shard id being retrained", "type": "integer" }, "triggering_revocation_event_seq": { "title": "events.seq of the consent.revoked event that triggered this retrain, when applicable", "type": "integer" } }, "required": [ "model_name", "shard_id", "prior_model_version" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Retrain shard (dry-run)", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.retrain_shard/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_retrain_shard`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_retrain_shard", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "model_name": { "title": "Model whose shard is retrained (ApiName form)", "type": "string" }, "prior_model_version": { "title": "The model version this retrain supersedes", "type": "integer" }, "reason": { "title": "Operator-facing reason for the retrain (audit metadata)", "type": "string" }, "shard_id": { "title": "SISA shard id being retrained", "type": "integer" }, "triggering_revocation_event_seq": { "title": "events.seq of the consent.revoked event that triggered this retrain, when applicable", "type": "integer" } }, "required": [ "model_name", "shard_id", "prior_model_version" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Retrain shard (dry-run)", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.retrain_shard/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_retrain_shard` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.retrain_shard:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_retrain_shard", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "model_name": { "title": "Model whose shard is retrained (ApiName form)", "type": "string" }, "prior_model_version": { "title": "The model version this retrain supersedes", "type": "integer" }, "reason": { "title": "Operator-facing reason for the retrain (audit metadata)", "type": "string" }, "shard_id": { "title": "SISA shard id being retrained", "type": "integer" }, "triggering_revocation_event_seq": { "title": "events.seq of the consent.revoked event that triggered this retrain, when applicable", "type": "integer" } }, "required": [ "model_name", "shard_id", "prior_model_version" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Retrain shard (rollup delta)", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.retry_guest_message_delivery/apply": { "post": { "description": "Send a failed message again: back to `queued` for the delivery adapter, to the address it was first meant for or — when there was none — the profile's contact as it is now (the desk has just added the number). Refused for a message that is not failed, for one the adapter has already handed over three times (write the guest a new message), and when the guest has since asked the house to stop.\n\nEffects: modify hospitality.guest_message.", "operationId": "apply_hospitality_action_retry_guest_message_delivery", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_message" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.guest_message" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.retry_guest_message_delivery:apply" ] } ], "summary": "Retry guest message delivery", "tags": [ "messaging" ] } }, "/v1/actions/hospitality.action.retry_guest_message_delivery/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_retry_guest_message_delivery` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.retry_guest_message_delivery:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_retry_guest_message_delivery", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_message" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.guest_message" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Retry guest message delivery (dry-run)", "tags": [ "messaging" ] } }, "/v1/actions/hospitality.action.retry_guest_message_delivery/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_retry_guest_message_delivery`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_retry_guest_message_delivery", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_message" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Retry guest message delivery (dry-run)", "tags": [ "messaging" ] } }, "/v1/actions/hospitality.action.retry_guest_message_delivery/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_retry_guest_message_delivery` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.retry_guest_message_delivery:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_retry_guest_message_delivery", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_message" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Retry guest message delivery (rollup delta)", "tags": [ "messaging" ] } }, "/v1/actions/hospitality.action.return_lost_found_item/apply": { "post": { "description": "Hand a found item back, or send it, to the person it belongs to — `person_id`, or the claimant when none is named. The item is `returned` (terminal) with the time and the person linked. Returning it again to the same person is a no-op, to anyone else is refused; a disposed item is refused, and so is an unclaimed item with no person named. Emits `lost_found_item.returned`.\n\nEffects: modify hospitality.lost_found_item; link hospitality.link.lost_found_item_returned_to.", "operationId": "apply_hospitality_action_return_lost_found_item", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "person_id": { "format": "uuid", "title": "Who it went to (defaults to the claimant)", "type": "string", "x-aerandil-references": "hospitality.person" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.lost_found_item" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.lost_found_item_returned_to" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.lost_found_item" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.return_lost_found_item:apply" ] } ], "summary": "Return lost & found item", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.return_lost_found_item/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_return_lost_found_item` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.return_lost_found_item:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_return_lost_found_item", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "person_id": { "format": "uuid", "title": "Who it went to (defaults to the claimant)", "type": "string", "x-aerandil-references": "hospitality.person" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.lost_found_item" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.lost_found_item_returned_to" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.lost_found_item" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Return lost & found item (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.return_lost_found_item/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_return_lost_found_item`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_return_lost_found_item", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "person_id": { "format": "uuid", "title": "Who it went to (defaults to the claimant)", "type": "string", "x-aerandil-references": "hospitality.person" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.lost_found_item" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Return lost & found item (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.return_lost_found_item/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_return_lost_found_item` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.return_lost_found_item:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_return_lost_found_item", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "person_id": { "format": "uuid", "title": "Who it went to (defaults to the claimant)", "type": "string", "x-aerandil-references": "hospitality.person" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.lost_found_item" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Return lost & found item (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.return_room_to_service/apply": { "post": { "description": "Release an active block early (the night audit releases through-date blocks on its own). Targets the block — a release is a statement about that window. Restores the availability rows the block itself decremented for dates from release_date on (lapsed nights stay counted: they were genuinely out of order), and the room re-enters the block's declared return_status unless overridden here. Releasing a released block is an idempotent no-op.\n\nEffects: modify hospitality.room_status_block; modify hospitality.room; modify hospitality.availability_day.", "operationId": "apply_hospitality_action_return_room_to_service", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "release_date": { "format": "date", "title": "First night back in service (defaults to today)", "type": "string" }, "return_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Override the block's declared return status", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room_status_block" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.room_status_block", "hospitality.room", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.return_room_to_service:apply" ] } ], "summary": "Return room to service", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.return_room_to_service/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_return_room_to_service` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.return_room_to_service:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_return_room_to_service", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "release_date": { "format": "date", "title": "First night back in service (defaults to today)", "type": "string" }, "return_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Override the block's declared return status", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room_status_block" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.room_status_block", "hospitality.room", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Return room to service (dry-run)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.return_room_to_service/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_return_room_to_service`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_return_room_to_service", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "release_date": { "format": "date", "title": "First night back in service (defaults to today)", "type": "string" }, "return_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Override the block's declared return status", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room_status_block" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Return room to service (dry-run)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.return_room_to_service/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_return_room_to_service` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.return_room_to_service:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_return_room_to_service", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "release_date": { "format": "date", "title": "First night back in service (defaults to today)", "type": "string" }, "return_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Override the block's declared return status", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room_status_block" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Return room to service (rollup delta)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.reverse_charge/apply": { "post": { "description": "Take back a posted charge by minting an equal-and-opposite reversal charge, linked to the original via `charge_reverses_charge`. Full-amount only: amount, tax lines, and gratuity are mirrored negated, so the pair nets to zero in the folio balance and in every per-bucket / per-kind rollup. The original stands (`voided` stays false) — both lines show, which is how a corrected bill reads. The reversal lands on the charge's own folio while it is open; once sealed, it lands on the open rebate folio linked via `folio_rebates_folio` — a sealed bill within the reopen window goes through `reopen_folio` first, beyond it through `open_rebate_folio`. Refuses a voided charge, a reversal charge (never chained — reverse the original), and a package-attributed charge (night-audit reconciliation owns those). Re-applying to an already-reversed charge is a no-op.\n\nEffects: create hospitality.charge; create hospitality.tax_application; link hospitality.link.folio_has_charge; link hospitality.link.charge_at_outlet; link hospitality.link.charge_for_service_item; link hospitality.link.charge_via_credential; link hospitality.link.charge_has_tax_application; link hospitality.link.charge_reverses_charge; modify hospitality.folio.", "operationId": "apply_hospitality_action_reverse_charge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "note": { "title": "Free-text detail; required when `reason` is `other`", "type": "string" }, "reason": { "enum": [ "duplicate_posting", "posting_error", "overcharge_correction", "disputed_item", "service_recovery", "other" ], "title": "Why the charge is being taken back", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.charge" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_charge", "hospitality.link.charge_at_outlet", "hospitality.link.charge_for_service_item", "hospitality.link.charge_via_credential", "hospitality.link.charge_has_tax_application", "hospitality.link.charge_reverses_charge" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.charge", "hospitality.tax_application", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.reverse_charge:apply" ] } ], "summary": "Reverse charge", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.reverse_charge/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_reverse_charge` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.reverse_charge:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_reverse_charge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "note": { "title": "Free-text detail; required when `reason` is `other`", "type": "string" }, "reason": { "enum": [ "duplicate_posting", "posting_error", "overcharge_correction", "disputed_item", "service_recovery", "other" ], "title": "Why the charge is being taken back", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.charge" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_charge", "hospitality.link.charge_at_outlet", "hospitality.link.charge_for_service_item", "hospitality.link.charge_via_credential", "hospitality.link.charge_has_tax_application", "hospitality.link.charge_reverses_charge" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.charge", "hospitality.tax_application", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Reverse charge (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.reverse_charge/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_reverse_charge`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_reverse_charge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "note": { "title": "Free-text detail; required when `reason` is `other`", "type": "string" }, "reason": { "enum": [ "duplicate_posting", "posting_error", "overcharge_correction", "disputed_item", "service_recovery", "other" ], "title": "Why the charge is being taken back", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.charge" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Reverse charge (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.reverse_charge/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_reverse_charge` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.reverse_charge:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_reverse_charge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "note": { "title": "Free-text detail; required when `reason` is `other`", "type": "string" }, "reason": { "enum": [ "duplicate_posting", "posting_error", "overcharge_correction", "disputed_item", "service_recovery", "other" ], "title": "Why the charge is being taken back", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.charge" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Reverse charge (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.review_agent_registry_entry/apply": { "post": { "description": "Record the curator's review verdict on a `submitted` registry entry: `approved` makes it installable (`agent_registry_approved_before_install`); `rejected` refuses it. Stamps `reviewed_by` / `reviewed_at` and emits `agent_registry_entry.reviewed`. Re-reviewing an entry already in the same verdict is a no-op; deprecation and blocking are their own actions with different installation semantics.\n\nEffects: modify hospitality.agent_registry_entry.", "operationId": "apply_hospitality_action_review_agent_registry_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "review_note": { "title": "Curator's review rationale", "type": "string" }, "review_status": { "enum": [ "submitted", "approved", "rejected", "deprecated", "blocked" ], "title": "approved | rejected", "type": "string" } }, "required": [ "review_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_registry_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.agent_registry_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.review_agent_registry_entry:apply" ] } ], "summary": "Review agent registry entry", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.review_agent_registry_entry/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_review_agent_registry_entry` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.review_agent_registry_entry:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_review_agent_registry_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "review_note": { "title": "Curator's review rationale", "type": "string" }, "review_status": { "enum": [ "submitted", "approved", "rejected", "deprecated", "blocked" ], "title": "approved | rejected", "type": "string" } }, "required": [ "review_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_registry_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.agent_registry_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Review agent registry entry (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.review_agent_registry_entry/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_review_agent_registry_entry`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_review_agent_registry_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "review_note": { "title": "Curator's review rationale", "type": "string" }, "review_status": { "enum": [ "submitted", "approved", "rejected", "deprecated", "blocked" ], "title": "approved | rejected", "type": "string" } }, "required": [ "review_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_registry_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Review agent registry entry (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.review_agent_registry_entry/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_review_agent_registry_entry` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.review_agent_registry_entry:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_review_agent_registry_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "review_note": { "title": "Curator's review rationale", "type": "string" }, "review_status": { "enum": [ "submitted", "approved", "rejected", "deprecated", "blocked" ], "title": "approved | rejected", "type": "string" } }, "required": [ "review_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_registry_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Review agent registry entry (rollup delta)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.revise_metric/apply": { "post": { "description": "Produce the next version of the targeted metric definition: version bumps by one, status returns to `draft`, and any prior certification is cleared — a revised definition must be re-certified (no silent un-deprecation either; revising a deprecated metric is exactly how it comes back). Omitted parameters keep their current values; supplied reference lists are re-validated against the Registry. The prior version stays in the object's event history. Emits `metric.revised`.\n\nEffects: modify hospitality.metric_definition.", "operationId": "apply_hospitality_action_revise_metric", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "description": { "title": "Disambiguating prose — the definition operators sign off on", "type": "string" }, "display_name": { "title": "Display name", "type": "string" }, "formula_expression": { "title": "Canonical formula expression (governed prose, not executed)", "type": "string" }, "grain": { "enum": [ "property_day", "property_month", "venue_day", "venue_month", "outlet_day", "brand_month", "portfolio_month", "tenant_month" ], "title": "Organisational-unit × period grain", "type": "string" }, "owner": { "title": "Accountable team / principal for the definition", "type": "string" }, "referenced_fields": { "items": { "type": "string" }, "title": "Registered `.` fields the formula reads", "type": "array" }, "referenced_object_types": { "items": { "type": "string" }, "title": "Registered object-type names the formula reads", "type": "array" }, "unit": { "enum": [ "money", "ratio", "percent", "count", "hours", "native_unit" ], "title": "Unit the metric's value carries", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.metric_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.metric_definition" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.revise_metric:apply" ] } ], "summary": "Revise metric", "tags": [ "catalogue" ] } }, "/v1/actions/hospitality.action.revise_metric/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_revise_metric` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.revise_metric:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_revise_metric", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "description": { "title": "Disambiguating prose — the definition operators sign off on", "type": "string" }, "display_name": { "title": "Display name", "type": "string" }, "formula_expression": { "title": "Canonical formula expression (governed prose, not executed)", "type": "string" }, "grain": { "enum": [ "property_day", "property_month", "venue_day", "venue_month", "outlet_day", "brand_month", "portfolio_month", "tenant_month" ], "title": "Organisational-unit × period grain", "type": "string" }, "owner": { "title": "Accountable team / principal for the definition", "type": "string" }, "referenced_fields": { "items": { "type": "string" }, "title": "Registered `.` fields the formula reads", "type": "array" }, "referenced_object_types": { "items": { "type": "string" }, "title": "Registered object-type names the formula reads", "type": "array" }, "unit": { "enum": [ "money", "ratio", "percent", "count", "hours", "native_unit" ], "title": "Unit the metric's value carries", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.metric_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.metric_definition" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Revise metric (dry-run)", "tags": [ "catalogue" ] } }, "/v1/actions/hospitality.action.revise_metric/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_revise_metric`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_revise_metric", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "description": { "title": "Disambiguating prose — the definition operators sign off on", "type": "string" }, "display_name": { "title": "Display name", "type": "string" }, "formula_expression": { "title": "Canonical formula expression (governed prose, not executed)", "type": "string" }, "grain": { "enum": [ "property_day", "property_month", "venue_day", "venue_month", "outlet_day", "brand_month", "portfolio_month", "tenant_month" ], "title": "Organisational-unit × period grain", "type": "string" }, "owner": { "title": "Accountable team / principal for the definition", "type": "string" }, "referenced_fields": { "items": { "type": "string" }, "title": "Registered `.` fields the formula reads", "type": "array" }, "referenced_object_types": { "items": { "type": "string" }, "title": "Registered object-type names the formula reads", "type": "array" }, "unit": { "enum": [ "money", "ratio", "percent", "count", "hours", "native_unit" ], "title": "Unit the metric's value carries", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.metric_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Revise metric (dry-run)", "tags": [ "catalogue" ] } }, "/v1/actions/hospitality.action.revise_metric/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_revise_metric` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.revise_metric:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_revise_metric", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "description": { "title": "Disambiguating prose — the definition operators sign off on", "type": "string" }, "display_name": { "title": "Display name", "type": "string" }, "formula_expression": { "title": "Canonical formula expression (governed prose, not executed)", "type": "string" }, "grain": { "enum": [ "property_day", "property_month", "venue_day", "venue_month", "outlet_day", "brand_month", "portfolio_month", "tenant_month" ], "title": "Organisational-unit × period grain", "type": "string" }, "owner": { "title": "Accountable team / principal for the definition", "type": "string" }, "referenced_fields": { "items": { "type": "string" }, "title": "Registered `.` fields the formula reads", "type": "array" }, "referenced_object_types": { "items": { "type": "string" }, "title": "Registered object-type names the formula reads", "type": "array" }, "unit": { "enum": [ "money", "ratio", "percent", "count", "hours", "native_unit" ], "title": "Unit the metric's value carries", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.metric_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Revise metric (rollup delta)", "tags": [ "catalogue" ] } }, "/v1/actions/hospitality.action.revoke_access_credential/apply": { "post": { "description": "Kill a credential: status → `revoked`, the token is REMOVED (the tap lookup only sees token-bearing rows, so a revoked card fails closed at the reader and its UID becomes free for re-issue), `token_hint` stays behind for audit. Idempotent on an already-revoked credential. Check-out does this automatically for every credential on the stay; this action is the manual path — lost card, guest request, fraud stop. Emits `access.credential_revoked.recorded`.\n\nEffects: modify hospitality.access_credential.", "operationId": "apply_hospitality_action_revoke_access_credential", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the credential was revoked (audit)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.access_credential" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.access_credential" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.revoke_access_credential:apply" ] } ], "summary": "Revoke access credential", "tags": [ "access" ] } }, "/v1/actions/hospitality.action.revoke_access_credential/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_revoke_access_credential` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.revoke_access_credential:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_revoke_access_credential", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the credential was revoked (audit)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.access_credential" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.access_credential" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Revoke access credential (dry-run)", "tags": [ "access" ] } }, "/v1/actions/hospitality.action.revoke_access_credential/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_revoke_access_credential`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_revoke_access_credential", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the credential was revoked (audit)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.access_credential" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Revoke access credential (dry-run)", "tags": [ "access" ] } }, "/v1/actions/hospitality.action.revoke_access_credential/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_revoke_access_credential` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.revoke_access_credential:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_revoke_access_credential", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the credential was revoked (audit)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.access_credential" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Revoke access credential (rollup delta)", "tags": [ "access" ] } }, "/v1/actions/hospitality.action.revoke_consent/apply": { "post": { "description": "Record a proposal 0026 §4 consent revocation on a subject object. Stamps the `consent_scope.revoked_at` tombstone (plus the `revocation_event_id` back-pointer) on the live row — the row stays live; revocation marks the scope, not the object — and emits `consent.revoked`. The subject is named by `subject_type` + `subject_id` (revocation must reach any governed object type, so it is not bound to a single target role). The background sweep worker then walks the lineage reverse-index to invalidate the inferences that depended on the revoked source.", "operationId": "apply_hospitality_action_revoke_consent", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Operator-facing reason for the revocation (audit metadata)", "type": "string" }, "subject_id": { "title": "Object id (uuid) of the subject whose consent is revoked", "type": "string" }, "subject_type": { "title": "Object type of the subject whose consent is revoked (ApiName)", "type": "string" } }, "required": [ "subject_type", "subject_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.revoke_consent:apply" ] } ], "summary": "Revoke consent", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.revoke_consent/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_revoke_consent` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.revoke_consent:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_revoke_consent", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Operator-facing reason for the revocation (audit metadata)", "type": "string" }, "subject_id": { "title": "Object id (uuid) of the subject whose consent is revoked", "type": "string" }, "subject_type": { "title": "Object type of the subject whose consent is revoked (ApiName)", "type": "string" } }, "required": [ "subject_type", "subject_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Revoke consent (dry-run)", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.revoke_consent/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_revoke_consent`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_revoke_consent", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Operator-facing reason for the revocation (audit metadata)", "type": "string" }, "subject_id": { "title": "Object id (uuid) of the subject whose consent is revoked", "type": "string" }, "subject_type": { "title": "Object type of the subject whose consent is revoked (ApiName)", "type": "string" } }, "required": [ "subject_type", "subject_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Revoke consent (dry-run)", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.revoke_consent/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_revoke_consent` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.revoke_consent:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_revoke_consent", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Operator-facing reason for the revocation (audit metadata)", "type": "string" }, "subject_id": { "title": "Object id (uuid) of the subject whose consent is revoked", "type": "string" }, "subject_type": { "title": "Object type of the subject whose consent is revoked (ApiName)", "type": "string" } }, "required": [ "subject_type", "subject_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Revoke consent (rollup delta)", "tags": [ "hospitality" ] } }, "/v1/actions/hospitality.action.revoke_purpose_grant/apply": { "post": { "description": "Revoke a `requested` or `active` grant — the operator kill-switch. Terminal; the row is kept for audit. Idempotent on an already-revoked grant. Emits `purpose_grant.revoked`.\n\nEffects: modify hospitality.purpose_grant.", "operationId": "apply_hospitality_action_revoke_purpose_grant", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the grant is being revoked", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.purpose_grant" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.purpose_grant" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.revoke_purpose_grant:apply" ] } ], "summary": "Revoke purpose grant", "tags": [ "pbac" ] } }, "/v1/actions/hospitality.action.revoke_purpose_grant/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_revoke_purpose_grant` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.revoke_purpose_grant:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_revoke_purpose_grant", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the grant is being revoked", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.purpose_grant" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.purpose_grant" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Revoke purpose grant (dry-run)", "tags": [ "pbac" ] } }, "/v1/actions/hospitality.action.revoke_purpose_grant/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_revoke_purpose_grant`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_revoke_purpose_grant", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the grant is being revoked", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.purpose_grant" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Revoke purpose grant (dry-run)", "tags": [ "pbac" ] } }, "/v1/actions/hospitality.action.revoke_purpose_grant/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_revoke_purpose_grant` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.revoke_purpose_grant:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_revoke_purpose_grant", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why the grant is being revoked", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.purpose_grant" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Revoke purpose grant (rollup delta)", "tags": [ "pbac" ] } }, "/v1/actions/hospitality.action.revoke_staff_certification/apply": { "post": { "description": "Revoke a certification grant (stamps revoked_at + reason). Non-destructive — the row stays as history.\n\nEffects: modify hospitality.staff_certification.", "operationId": "apply_hospitality_action_revoke_staff_certification", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "revoked_reason": { "title": "Revocation reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_certification" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.staff_certification" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.revoke_staff_certification:apply" ] } ], "summary": "Revoke staff certification", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.revoke_staff_certification/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_revoke_staff_certification` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.revoke_staff_certification:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_revoke_staff_certification", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "revoked_reason": { "title": "Revocation reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_certification" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.staff_certification" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Revoke staff certification (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.revoke_staff_certification/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_revoke_staff_certification`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_revoke_staff_certification", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "revoked_reason": { "title": "Revocation reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_certification" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Revoke staff certification (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.revoke_staff_certification/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_revoke_staff_certification` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.revoke_staff_certification:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_revoke_staff_certification", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "revoked_reason": { "title": "Revocation reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_certification" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Revoke staff certification (rollup delta)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.revoke_tax_exemption/apply": { "post": { "description": "Stop a booking's tax exemption from now on: stamps the one in force with `revoked_at`. Postings made while it applied keep their (absent) tax — correcting those is a reversal and a re-post, not a rewrite. Refuses a booking with no exemption in force.\n\nEffects: modify hospitality.tax_exemption.", "operationId": "apply_hospitality_action_revoke_tax_exemption", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.tax_exemption" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.revoke_tax_exemption:apply" ] } ], "summary": "Revoke tax exemption", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.revoke_tax_exemption/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_revoke_tax_exemption` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.revoke_tax_exemption:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_revoke_tax_exemption", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.tax_exemption" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Revoke tax exemption (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.revoke_tax_exemption/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_revoke_tax_exemption`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_revoke_tax_exemption", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Revoke tax exemption (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.revoke_tax_exemption/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_revoke_tax_exemption` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.revoke_tax_exemption:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_revoke_tax_exemption", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Revoke tax exemption (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.run_automation_now/apply": { "post": { "description": "Fire an `active` scheduled automation — a `time_cron` rule or an `object_set_all` sweep — now, off its clock: the operator's \"fire the effect by hand\", and how a gate proves a sweep without waiting for its quarter hour. The verb records the request (`automation.run_requested`); the automation lane's event tail fires the rule once for it, exactly as its schedule would — a sweep over the objects matching its filter at the instant of the request, a cron rule's effect once — through the same effectively-once claim (keyed on the request), the same approval staging and the same run artefact, so the run is read where every run is (`automation_run`). Refused on an automation that is not active and on an event-driven one (it fires on its event, and has no firing without one), and to an automation's own principal (rules chain by events, not by running each other). Writes nothing else; with the automation lane off, the request is recorded and nothing fires.", "operationId": "apply_hospitality_action_run_automation_now", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.automation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.run_automation_now:apply" ] } ], "summary": "Run automation now", "tags": [ "automation" ] } }, "/v1/actions/hospitality.action.run_automation_now/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_run_automation_now` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.run_automation_now:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_run_automation_now", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.automation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Run automation now (dry-run)", "tags": [ "automation" ] } }, "/v1/actions/hospitality.action.run_automation_now/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_run_automation_now`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_run_automation_now", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.automation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Run automation now (dry-run)", "tags": [ "automation" ] } }, "/v1/actions/hospitality.action.run_automation_now/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_run_automation_now` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.run_automation_now:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_run_automation_now", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.automation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Run automation now (rollup delta)", "tags": [ "automation" ] } }, "/v1/actions/hospitality.action.run_night_audit/apply": { "post": { "description": "Close the property's open business date — a real audit, not a bookkeeping stamp, and never a blocking batch: the whole run is one transaction (a failure rolls everything back and the day stays open; a re-run replays idempotently), and nothing else stops while it runs. In order: (1) sweeps the day's unresolved arrivals to no_show through the mark_reservation_no_show path, releasing their forward room-nights — and on partially-arrived multi-room reservations cancels the individual legs that never showed, releasing theirs (disable with sweep_no_shows = false); (1a) assesses the no-show fee from the reservation's frozen cancellation policy and posts it as a rooms-bucket no_show_fee charge, recording the amount and an `assessed` status on the reservation — OPERA's Post-Revenue-To-No-Shows, and like OPERA's it is **opt-in**: enable with post_no_show_fees = true. The fee carries the tax the house's rules for a `no_show_fee` produce, and none where it authored none (the UK taxes it, Austria does not); a booking's tax exemption reaches it. Assessment only; collecting the fee off-session against a stored card is a separate step, because the audit runs inside the ontology and the card rail does not; (1c) releases group-block rooms nobody picked up, per each definite block's cutoff mode — after the no-show sweep, so a room a no-show hands back to its block is cut off the same night rather than sitting held for a day (disable with release_block_cutoffs = false); (1d) accrues commission on stays that departed today — one row per payee, with the contract that produced it frozen on the row (disable with accrue_commission = false); (1e) expires waitlist entries two business days past their requested departure — OPERA's End-of-Day auto-delete, as a terminal status rather than a deletion, so the turnaway stays countable (disable with expire_waitlist = false); (1g) strips the booking engine's visitor key from the offers, turnaways and reservations whose arrival night is the property's visitor_key_grace_days past (30 unset), keeping the records — the key only joins records of one night (disable with strip_visitor_keys = false); (1h) expires payment requests still pending whose expires_at falls on or before the audited date — the pay link lapses at the close (always on; absent from the summary when none expired); (2) posts the night's room charge to every in-house stay's window-1 folio from its reservation_night rate — replay-safe via the charge external_ref business key, complimentary nights skipped, tax_application lines derived from the property's active rooms tax_rule rows (inclusive rules carve out of the rate, exclusive rules join the folio debit; no rules = zero tax) — disable with post_room_and_tax = false; (2c) balances package allowances: components due on the closing date with no consumption row settle as profit — an append-only consumption row plus the package_discount_adjustment charge, replay-safe (disable with balance_packages = false); (3) counts exceptions instead of halting on them — due-outs still in house, open cashier sessions, unresolvable folios, malformed tax or package config — the OPERA halt conditions turned into a queue (the date roll never waits on a drawer); (4) mints an immutable NightAuditRun carrying posted_room_revenue, posted_room_tax, package_adjustments_posted and exception_count (re-runs create new rows, never edit); (5) closes the BusinessDate and rolls the next day open (disable with open_next = false), moving the property's open_business_date to it — or clearing it when nothing is opened — so postings from the close on are dated to the new hotel date.\n\nEffects: modify hospitality.property; modify hospitality.block_allocation; modify hospitality.waitlist_entry; modify hospitality.payment_request; modify hospitality.stay_offer; modify hospitality.turnaway; modify hospitality.payment_card; create hospitality.commission_detail; link hospitality.link.commission_detail_for_reservation; link hospitality.link.commission_detail_owed_to_company; link hospitality.link.commission_detail_owed_to_channel; create hospitality.night_audit_run; modify hospitality.business_date; create hospitality.business_date; modify hospitality.reservation; modify hospitality.reservation_room; modify hospitality.availability_day; create hospitality.charge; link hospitality.link.folio_has_charge; link hospitality.link.charge_at_outlet; modify hospitality.folio; create hospitality.folio; link hospitality.link.reservation_has_folio; create hospitality.tax_application; link hospitality.link.charge_has_tax_application; create hospitality.package_component_consumption; link hospitality.link.package_sale_has_consumption; link hospitality.link.consumption_for_charge; link hospitality.link.charge_attributed_to_package_sale; link hospitality.link.charge_attributed_to_package_component; modify hospitality.room_status_block; modify hospitality.room; modify hospitality.share_group; unlink hospitality.link.reservation_in_share_group; link hospitality.link.charge_for_service_item; create hospitality.payment; link hospitality.link.folio_has_payment.", "operationId": "apply_hospitality_action_run_night_audit", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "accrue_commission": { "title": "Accrue travel-agent and channel commission on stays that completed today (defaults to true)", "type": "boolean" }, "balance_packages": { "title": "Settle unconsumed package allowances due on the closing date as profit (defaults to true)", "type": "boolean" }, "business_date": { "format": "date", "title": "Business date", "type": "string" }, "enforce_deposits": { "title": "Cancel expired courtesy holds and lapsed wholly-unpaid deposits whose frozen policy says auto-cancel; record other lapses for the operator (defaults to true)", "type": "boolean" }, "expire_waitlist": { "title": "Age out waitlist entries two business days past their requested departure (defaults to true)", "type": "boolean" }, "open_next": { "title": "Open the next business date after closing this one (defaults to true)", "type": "boolean" }, "post_no_show_fees": { "title": "Assess and post the cancellation policy's no-show fee for reservations swept to no_show (defaults to FALSE — posting revenue to no-shows is a policy decision, not a default)", "type": "boolean" }, "post_room_and_tax": { "title": "Post the night's room charges to in-house folios (defaults to true)", "type": "boolean" }, "release_block_cutoffs": { "title": "Release group-block rooms nobody picked up, per each block's cutoff mode (defaults to true)", "type": "boolean" }, "retire_expired_cards": { "title": "Mark cards on file whose expiry month has passed as `expired`, so nothing offers a guarantee the issuer will decline (defaults to true)", "type": "boolean" }, "strip_visitor_keys": { "title": "Strip the visitor key from offers, turnaways and reservations whose arrival night is past the property's grace (defaults to true)", "type": "boolean" }, "sweep_no_shows": { "title": "Sweep unresolved arrivals to no_show (defaults to true)", "type": "boolean" } }, "required": [ "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.commission_detail_for_reservation", "hospitality.link.commission_detail_owed_to_company", "hospitality.link.commission_detail_owed_to_channel", "hospitality.link.folio_has_charge", "hospitality.link.charge_at_outlet", "hospitality.link.reservation_has_folio", "hospitality.link.charge_has_tax_application", "hospitality.link.package_sale_has_consumption", "hospitality.link.consumption_for_charge", "hospitality.link.charge_attributed_to_package_sale", "hospitality.link.charge_attributed_to_package_component", "hospitality.link.reservation_in_share_group", "hospitality.link.charge_for_service_item", "hospitality.link.folio_has_payment" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.property", "hospitality.block_allocation", "hospitality.waitlist_entry", "hospitality.payment_request", "hospitality.stay_offer", "hospitality.turnaway", "hospitality.payment_card", "hospitality.commission_detail", "hospitality.night_audit_run", "hospitality.business_date", "hospitality.reservation", "hospitality.reservation_room", "hospitality.availability_day", "hospitality.charge", "hospitality.folio", "hospitality.tax_application", "hospitality.package_component_consumption", "hospitality.room_status_block", "hospitality.room", "hospitality.share_group", "hospitality.payment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.run_night_audit:apply" ] } ], "summary": "Run night audit", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.run_night_audit/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_run_night_audit` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.run_night_audit:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_run_night_audit", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "accrue_commission": { "title": "Accrue travel-agent and channel commission on stays that completed today (defaults to true)", "type": "boolean" }, "balance_packages": { "title": "Settle unconsumed package allowances due on the closing date as profit (defaults to true)", "type": "boolean" }, "business_date": { "format": "date", "title": "Business date", "type": "string" }, "enforce_deposits": { "title": "Cancel expired courtesy holds and lapsed wholly-unpaid deposits whose frozen policy says auto-cancel; record other lapses for the operator (defaults to true)", "type": "boolean" }, "expire_waitlist": { "title": "Age out waitlist entries two business days past their requested departure (defaults to true)", "type": "boolean" }, "open_next": { "title": "Open the next business date after closing this one (defaults to true)", "type": "boolean" }, "post_no_show_fees": { "title": "Assess and post the cancellation policy's no-show fee for reservations swept to no_show (defaults to FALSE — posting revenue to no-shows is a policy decision, not a default)", "type": "boolean" }, "post_room_and_tax": { "title": "Post the night's room charges to in-house folios (defaults to true)", "type": "boolean" }, "release_block_cutoffs": { "title": "Release group-block rooms nobody picked up, per each block's cutoff mode (defaults to true)", "type": "boolean" }, "retire_expired_cards": { "title": "Mark cards on file whose expiry month has passed as `expired`, so nothing offers a guarantee the issuer will decline (defaults to true)", "type": "boolean" }, "strip_visitor_keys": { "title": "Strip the visitor key from offers, turnaways and reservations whose arrival night is past the property's grace (defaults to true)", "type": "boolean" }, "sweep_no_shows": { "title": "Sweep unresolved arrivals to no_show (defaults to true)", "type": "boolean" } }, "required": [ "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.commission_detail_for_reservation", "hospitality.link.commission_detail_owed_to_company", "hospitality.link.commission_detail_owed_to_channel", "hospitality.link.folio_has_charge", "hospitality.link.charge_at_outlet", "hospitality.link.reservation_has_folio", "hospitality.link.charge_has_tax_application", "hospitality.link.package_sale_has_consumption", "hospitality.link.consumption_for_charge", "hospitality.link.charge_attributed_to_package_sale", "hospitality.link.charge_attributed_to_package_component", "hospitality.link.reservation_in_share_group", "hospitality.link.charge_for_service_item", "hospitality.link.folio_has_payment" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.property", "hospitality.block_allocation", "hospitality.waitlist_entry", "hospitality.payment_request", "hospitality.stay_offer", "hospitality.turnaway", "hospitality.payment_card", "hospitality.commission_detail", "hospitality.night_audit_run", "hospitality.business_date", "hospitality.reservation", "hospitality.reservation_room", "hospitality.availability_day", "hospitality.charge", "hospitality.folio", "hospitality.tax_application", "hospitality.package_component_consumption", "hospitality.room_status_block", "hospitality.room", "hospitality.share_group", "hospitality.payment" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Run night audit (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.run_night_audit/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_run_night_audit`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_run_night_audit", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "accrue_commission": { "title": "Accrue travel-agent and channel commission on stays that completed today (defaults to true)", "type": "boolean" }, "balance_packages": { "title": "Settle unconsumed package allowances due on the closing date as profit (defaults to true)", "type": "boolean" }, "business_date": { "format": "date", "title": "Business date", "type": "string" }, "enforce_deposits": { "title": "Cancel expired courtesy holds and lapsed wholly-unpaid deposits whose frozen policy says auto-cancel; record other lapses for the operator (defaults to true)", "type": "boolean" }, "expire_waitlist": { "title": "Age out waitlist entries two business days past their requested departure (defaults to true)", "type": "boolean" }, "open_next": { "title": "Open the next business date after closing this one (defaults to true)", "type": "boolean" }, "post_no_show_fees": { "title": "Assess and post the cancellation policy's no-show fee for reservations swept to no_show (defaults to FALSE — posting revenue to no-shows is a policy decision, not a default)", "type": "boolean" }, "post_room_and_tax": { "title": "Post the night's room charges to in-house folios (defaults to true)", "type": "boolean" }, "release_block_cutoffs": { "title": "Release group-block rooms nobody picked up, per each block's cutoff mode (defaults to true)", "type": "boolean" }, "retire_expired_cards": { "title": "Mark cards on file whose expiry month has passed as `expired`, so nothing offers a guarantee the issuer will decline (defaults to true)", "type": "boolean" }, "strip_visitor_keys": { "title": "Strip the visitor key from offers, turnaways and reservations whose arrival night is past the property's grace (defaults to true)", "type": "boolean" }, "sweep_no_shows": { "title": "Sweep unresolved arrivals to no_show (defaults to true)", "type": "boolean" } }, "required": [ "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Run night audit (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.run_night_audit/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_run_night_audit` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.run_night_audit:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_run_night_audit", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "accrue_commission": { "title": "Accrue travel-agent and channel commission on stays that completed today (defaults to true)", "type": "boolean" }, "balance_packages": { "title": "Settle unconsumed package allowances due on the closing date as profit (defaults to true)", "type": "boolean" }, "business_date": { "format": "date", "title": "Business date", "type": "string" }, "enforce_deposits": { "title": "Cancel expired courtesy holds and lapsed wholly-unpaid deposits whose frozen policy says auto-cancel; record other lapses for the operator (defaults to true)", "type": "boolean" }, "expire_waitlist": { "title": "Age out waitlist entries two business days past their requested departure (defaults to true)", "type": "boolean" }, "open_next": { "title": "Open the next business date after closing this one (defaults to true)", "type": "boolean" }, "post_no_show_fees": { "title": "Assess and post the cancellation policy's no-show fee for reservations swept to no_show (defaults to FALSE — posting revenue to no-shows is a policy decision, not a default)", "type": "boolean" }, "post_room_and_tax": { "title": "Post the night's room charges to in-house folios (defaults to true)", "type": "boolean" }, "release_block_cutoffs": { "title": "Release group-block rooms nobody picked up, per each block's cutoff mode (defaults to true)", "type": "boolean" }, "retire_expired_cards": { "title": "Mark cards on file whose expiry month has passed as `expired`, so nothing offers a guarantee the issuer will decline (defaults to true)", "type": "boolean" }, "strip_visitor_keys": { "title": "Strip the visitor key from offers, turnaways and reservations whose arrival night is past the property's grace (defaults to true)", "type": "boolean" }, "sweep_no_shows": { "title": "Sweep unresolved arrivals to no_show (defaults to true)", "type": "boolean" } }, "required": [ "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Run night audit (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.schedule_work_order/apply": { "post": { "description": "Commit the work to a date: open / blocked / postponed → scheduled (re-scheduling a scheduled order just moves the date). Clears any block reason and postponement — a scheduled order is no longer waiting, and scheduling a postponed order is its resume.\n\nEffects: modify hospitality.work_order.", "operationId": "apply_hospitality_action_schedule_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "scheduled_for": { "format": "date", "title": "Date the work is committed to", "type": "string" } }, "required": [ "scheduled_for" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.work_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.schedule_work_order:apply" ] } ], "summary": "Schedule work order", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.schedule_work_order/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_schedule_work_order` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.schedule_work_order:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_schedule_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "scheduled_for": { "format": "date", "title": "Date the work is committed to", "type": "string" } }, "required": [ "scheduled_for" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.work_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Schedule work order (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.schedule_work_order/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_schedule_work_order`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_schedule_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "scheduled_for": { "format": "date", "title": "Date the work is committed to", "type": "string" } }, "required": [ "scheduled_for" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Schedule work order (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.schedule_work_order/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_schedule_work_order` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.schedule_work_order:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_schedule_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "scheduled_for": { "format": "date", "title": "Date the work is committed to", "type": "string" } }, "required": [ "scheduled_for" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Schedule work order (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.separate_share/apply": { "post": { "description": "Break a share group: every member becomes an independent reservation again. Each date covered by k members re-consumes k-1 room-nights through the guarded availability path, so separating into a sold-out house refuses atomically instead of overselling silently. Pre-arrival members only — an in-house break forces a room move (deferred). Rates are not restored after a split; re-pricing is an explicit modify_reservation_dates requote/override. Membership links are end-dated, keeping the share as auditable history; separating an already separated group is a no-op.\n\nEffects: modify hospitality.share_group; modify hospitality.availability_day; unlink hospitality.link.reservation_in_share_group.", "operationId": "apply_hospitality_action_separate_share", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.share_group" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.reservation_in_share_group" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.share_group", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.separate_share:apply" ] } ], "summary": "Separate share", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.separate_share/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_separate_share` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.separate_share:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_separate_share", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.share_group" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.reservation_in_share_group" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.share_group", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Separate share (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.separate_share/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_separate_share`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_separate_share", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.share_group" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Separate share (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.separate_share/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_separate_share` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.separate_share:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_separate_share", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.share_group" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Separate share (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.set_asset_status/apply": { "post": { "description": "Put a piece of equipment out of service (with the reason) or back in service. Refuses a retired asset — retirement is retire_asset's, and final. Setting the status it already has, with the same reason, is a no-op.\n\nEffects: modify hospitality.asset.", "operationId": "apply_hospitality_action_set_asset_status", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why it is out of service (required for out_of_service)", "type": "string" }, "status": { "enum": [ "active", "out_of_service" ], "title": "active or out_of_service", "type": "string" } }, "required": [ "status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.asset" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.asset" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_asset_status:apply" ] } ], "summary": "Set asset status", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.set_asset_status/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_asset_status` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_asset_status:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_asset_status", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why it is out of service (required for out_of_service)", "type": "string" }, "status": { "enum": [ "active", "out_of_service" ], "title": "active or out_of_service", "type": "string" } }, "required": [ "status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.asset" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.asset" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set asset status (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.set_asset_status/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_asset_status`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_asset_status", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why it is out of service (required for out_of_service)", "type": "string" }, "status": { "enum": [ "active", "out_of_service" ], "title": "active or out_of_service", "type": "string" } }, "required": [ "status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.asset" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set asset status (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.set_asset_status/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_asset_status` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_asset_status:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_asset_status", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why it is out of service (required for out_of_service)", "type": "string" }, "status": { "enum": [ "active", "out_of_service" ], "title": "active or out_of_service", "type": "string" } }, "required": [ "status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.asset" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set asset status (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.set_availability/apply": { "post": { "description": "Author the inventory ledger for a (property, room_type) pair over a date range, optionally masked to days of the week. Upserts the canonical `availability_day` rows: an existing row's physical / sellable / oversell_limit are re-set in place with its `sold` count untouched (the booking flow owns `sold`); a missing row is minted with `sold` from the optional `sold` parameter (default 0 — pass it only when seeding a ledger under bookings that already exist). The availability_day validator enforces `sellable <= physical` and `0 <= sold <= sellable + oversell_limit` on every write either way. This is the operator's declaration: `oversell_limit` is written as the limit in force and as `declared_oversell_limit` (what a sell-limit recommendation's reset restores), replacing any applied recommendation's limit, and `oversell_ceiling` — the most headroom a recommendation may set — with it; an omitted one clears, as the call states the whole cell.\n\nEffects: create hospitality.availability_day; modify hospitality.availability_day; link hospitality.link.property_has_availability_day; link hospitality.link.room_type_has_availability_day.", "operationId": "apply_hospitality_action_set_availability", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "days_of_week": { "items": { "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "type": "string" }, "title": "Days of week the pattern applies to (defaults to all seven)", "type": "array" }, "end_date": { "format": "date", "title": "End date (inclusive)", "type": "string" }, "oversell_ceiling": { "description": "The most oversell headroom a sell-limit recommendation may set (the guardrail; omitted, the declared oversell_limit is the ceiling)", "title": "Oversell ceiling", "type": "integer" }, "oversell_limit": { "title": "Oversell headroom above sellable", "type": "integer" }, "physical": { "title": "Physical room count", "type": "integer" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "room_type_id": { "format": "uuid", "title": "Room type", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "sellable": { "title": "Sellable room count", "type": "integer" }, "sold": { "title": "Initial sold count for rows this call mints (default 0; existing rows keep their own)", "type": "integer" }, "start_date": { "format": "date", "title": "Start date", "type": "string" } }, "required": [ "property_id", "room_type_id", "start_date", "end_date", "physical", "sellable" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.property_has_availability_day", "hospitality.link.room_type_has_availability_day" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_availability:apply" ] } ], "summary": "Set availability", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.set_availability/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_availability` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_availability:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_availability", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "days_of_week": { "items": { "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "type": "string" }, "title": "Days of week the pattern applies to (defaults to all seven)", "type": "array" }, "end_date": { "format": "date", "title": "End date (inclusive)", "type": "string" }, "oversell_ceiling": { "description": "The most oversell headroom a sell-limit recommendation may set (the guardrail; omitted, the declared oversell_limit is the ceiling)", "title": "Oversell ceiling", "type": "integer" }, "oversell_limit": { "title": "Oversell headroom above sellable", "type": "integer" }, "physical": { "title": "Physical room count", "type": "integer" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "room_type_id": { "format": "uuid", "title": "Room type", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "sellable": { "title": "Sellable room count", "type": "integer" }, "sold": { "title": "Initial sold count for rows this call mints (default 0; existing rows keep their own)", "type": "integer" }, "start_date": { "format": "date", "title": "Start date", "type": "string" } }, "required": [ "property_id", "room_type_id", "start_date", "end_date", "physical", "sellable" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.property_has_availability_day", "hospitality.link.room_type_has_availability_day" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set availability (dry-run)", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.set_availability/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_availability`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_availability", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "days_of_week": { "items": { "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "type": "string" }, "title": "Days of week the pattern applies to (defaults to all seven)", "type": "array" }, "end_date": { "format": "date", "title": "End date (inclusive)", "type": "string" }, "oversell_ceiling": { "description": "The most oversell headroom a sell-limit recommendation may set (the guardrail; omitted, the declared oversell_limit is the ceiling)", "title": "Oversell ceiling", "type": "integer" }, "oversell_limit": { "title": "Oversell headroom above sellable", "type": "integer" }, "physical": { "title": "Physical room count", "type": "integer" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "room_type_id": { "format": "uuid", "title": "Room type", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "sellable": { "title": "Sellable room count", "type": "integer" }, "sold": { "title": "Initial sold count for rows this call mints (default 0; existing rows keep their own)", "type": "integer" }, "start_date": { "format": "date", "title": "Start date", "type": "string" } }, "required": [ "property_id", "room_type_id", "start_date", "end_date", "physical", "sellable" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set availability (dry-run)", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.set_availability/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_availability` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_availability:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_availability", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "days_of_week": { "items": { "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "type": "string" }, "title": "Days of week the pattern applies to (defaults to all seven)", "type": "array" }, "end_date": { "format": "date", "title": "End date (inclusive)", "type": "string" }, "oversell_ceiling": { "description": "The most oversell headroom a sell-limit recommendation may set (the guardrail; omitted, the declared oversell_limit is the ceiling)", "title": "Oversell ceiling", "type": "integer" }, "oversell_limit": { "title": "Oversell headroom above sellable", "type": "integer" }, "physical": { "title": "Physical room count", "type": "integer" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "room_type_id": { "format": "uuid", "title": "Room type", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "sellable": { "title": "Sellable room count", "type": "integer" }, "sold": { "title": "Initial sold count for rows this call mints (default 0; existing rows keep their own)", "type": "integer" }, "start_date": { "format": "date", "title": "Start date", "type": "string" } }, "required": [ "property_id", "room_type_id", "start_date", "end_date", "physical", "sellable" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set availability (rollup delta)", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.set_bed_configuration/apply": { "post": { "description": "Record how the room's convertible beds are made up now — joined (one double or king) or split (two singles) — hubOS's beds-configuration write; or clear it when `bed_configuration` is absent (beds that no longer convert). The room's state, which the floor moves when it splits or joins the beds and the desk when a guest asks; the room type's free-text `bed_configuration` is what the type is sold as and is not touched. Any read of the room — the rack, a task's room — carries it. Setting the value the room already carries is a no-op. Emits `room.bed_configuration_set` with the value it replaced.\n\nEffects: modify hospitality.room.", "operationId": "apply_hospitality_action_set_bed_configuration", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "bed_configuration": { "enum": [ "joined", "split" ], "title": "joined or split; absent clears it", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.room" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_bed_configuration:apply" ] } ], "summary": "Set bed configuration", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.set_bed_configuration/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_bed_configuration` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_bed_configuration:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_bed_configuration", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "bed_configuration": { "enum": [ "joined", "split" ], "title": "joined or split; absent clears it", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.room" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set bed configuration (dry-run)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.set_bed_configuration/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_bed_configuration`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_bed_configuration", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "bed_configuration": { "enum": [ "joined", "split" ], "title": "joined or split; absent clears it", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set bed configuration (dry-run)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.set_bed_configuration/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_bed_configuration` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_bed_configuration:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_bed_configuration", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "bed_configuration": { "enum": [ "joined", "split" ], "title": "joined or split; absent clears it", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set bed configuration (rollup delta)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.set_block_allocation/apply": { "post": { "description": "Set how many rooms of one room type the block holds across a date range — one grid cell per night. On a `definite` block the change moves inventory immediately, maintaining `availability_day.blocked`. Refuses to drop a night's allotment below what has already been picked up.\n\nEffects: create hospitality.block_allocation; modify hospitality.block_allocation; modify hospitality.availability_day; link hospitality.link.block_allocation_of_block; link hospitality.link.block_allocation_for_room_type.", "operationId": "apply_hospitality_action_set_block_allocation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "from_date": { "format": "date", "title": "First night", "type": "string" }, "rate_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Per-cell rate override", "type": "object" }, "room_type_id": { "format": "uuid", "title": "Room type", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "rooms": { "title": "Rooms to hold per night", "type": "integer" }, "to_date": { "format": "date", "title": "End of range (exclusive)", "type": "string" } }, "required": [ "room_type_id", "from_date", "to_date", "rooms" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_block" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.block_allocation_of_block", "hospitality.link.block_allocation_for_room_type" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.block_allocation", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_block_allocation:apply" ] } ], "summary": "Set block allocation", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.set_block_allocation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_block_allocation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_block_allocation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_block_allocation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "from_date": { "format": "date", "title": "First night", "type": "string" }, "rate_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Per-cell rate override", "type": "object" }, "room_type_id": { "format": "uuid", "title": "Room type", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "rooms": { "title": "Rooms to hold per night", "type": "integer" }, "to_date": { "format": "date", "title": "End of range (exclusive)", "type": "string" } }, "required": [ "room_type_id", "from_date", "to_date", "rooms" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_block" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.block_allocation_of_block", "hospitality.link.block_allocation_for_room_type" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.block_allocation", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set block allocation (dry-run)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.set_block_allocation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_block_allocation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_block_allocation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "from_date": { "format": "date", "title": "First night", "type": "string" }, "rate_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Per-cell rate override", "type": "object" }, "room_type_id": { "format": "uuid", "title": "Room type", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "rooms": { "title": "Rooms to hold per night", "type": "integer" }, "to_date": { "format": "date", "title": "End of range (exclusive)", "type": "string" } }, "required": [ "room_type_id", "from_date", "to_date", "rooms" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_block" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set block allocation (dry-run)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.set_block_allocation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_block_allocation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_block_allocation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_block_allocation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "from_date": { "format": "date", "title": "First night", "type": "string" }, "rate_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Per-cell rate override", "type": "object" }, "room_type_id": { "format": "uuid", "title": "Room type", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "rooms": { "title": "Rooms to hold per night", "type": "integer" }, "to_date": { "format": "date", "title": "End of range (exclusive)", "type": "string" } }, "required": [ "room_type_id", "from_date", "to_date", "rooms" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_block" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set block allocation (rollup delta)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.set_board_sort_pattern/apply": { "post": { "description": "Set the order of one of the property's boards — hubOS's server-defined sort pattern: the attendant's housekeeping_sheet, the supervisor's housekeeping_rack, the engineer's work_orders board, or the pacing report. `keys` is ordered, first key first, each a key the board's rows carry (priority, room_number, floor, task_type, status, credits, arrival_time, departure_time on the housekeeping boards; priority — the order's severity — room_number, floor, status, due_at on work_orders; name, credits, pending_credits, target_percent on pacing) with a direction, and for a ranked key (priority, task_type, status) optionally the house's order of its values, least first (departures before stayovers). One pattern per board per house: setting a board again replaces its pattern in place and revives it if it was retired; the same order again writes nothing. A staff member's own preference (set_staff_sort_preference) wins over it; `board_sort` reads the order a caller sees. Emits `board_sort_pattern.set.recorded`.\n\nEffects: create hospitality.board_sort_pattern; modify hospitality.board_sort_pattern; link hospitality.link.board_sort_pattern_at_property.", "operationId": "apply_hospitality_action_set_board_sort_pattern", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "board": { "enum": [ "housekeeping_sheet", "housekeeping_rack", "work_orders", "pacing" ], "title": "The board to order", "type": "string" }, "keys": { "items": { "properties": { "direction": { "enum": [ "asc", "desc" ], "type": "string" }, "key": { "enum": [ "priority", "room_number", "floor", "task_type", "status", "due_at", "credits", "arrival_time", "departure_time", "pending_credits", "target_percent", "name" ], "type": "string" }, "values": { "items": { "type": "string" }, "type": "array" } }, "required": [ "key", "direction" ], "type": "object" }, "title": "Sort keys", "type": "array" } }, "required": [ "board", "keys" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.board_sort_pattern_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.board_sort_pattern" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_board_sort_pattern:apply" ] } ], "summary": "Set board sort pattern", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_board_sort_pattern/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_board_sort_pattern` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_board_sort_pattern:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_board_sort_pattern", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "board": { "enum": [ "housekeeping_sheet", "housekeeping_rack", "work_orders", "pacing" ], "title": "The board to order", "type": "string" }, "keys": { "items": { "properties": { "direction": { "enum": [ "asc", "desc" ], "type": "string" }, "key": { "enum": [ "priority", "room_number", "floor", "task_type", "status", "due_at", "credits", "arrival_time", "departure_time", "pending_credits", "target_percent", "name" ], "type": "string" }, "values": { "items": { "type": "string" }, "type": "array" } }, "required": [ "key", "direction" ], "type": "object" }, "title": "Sort keys", "type": "array" } }, "required": [ "board", "keys" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.board_sort_pattern_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.board_sort_pattern" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set board sort pattern (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_board_sort_pattern/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_board_sort_pattern`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_board_sort_pattern", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "board": { "enum": [ "housekeeping_sheet", "housekeeping_rack", "work_orders", "pacing" ], "title": "The board to order", "type": "string" }, "keys": { "items": { "properties": { "direction": { "enum": [ "asc", "desc" ], "type": "string" }, "key": { "enum": [ "priority", "room_number", "floor", "task_type", "status", "due_at", "credits", "arrival_time", "departure_time", "pending_credits", "target_percent", "name" ], "type": "string" }, "values": { "items": { "type": "string" }, "type": "array" } }, "required": [ "key", "direction" ], "type": "object" }, "title": "Sort keys", "type": "array" } }, "required": [ "board", "keys" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set board sort pattern (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_board_sort_pattern/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_board_sort_pattern` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_board_sort_pattern:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_board_sort_pattern", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "board": { "enum": [ "housekeeping_sheet", "housekeeping_rack", "work_orders", "pacing" ], "title": "The board to order", "type": "string" }, "keys": { "items": { "properties": { "direction": { "enum": [ "asc", "desc" ], "type": "string" }, "key": { "enum": [ "priority", "room_number", "floor", "task_type", "status", "due_at", "credits", "arrival_time", "departure_time", "pending_credits", "target_percent", "name" ], "type": "string" }, "values": { "items": { "type": "string" }, "type": "array" } }, "required": [ "key", "direction" ], "type": "object" }, "title": "Sort keys", "type": "array" } }, "required": [ "board", "keys" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set board sort pattern (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_cancellation_policy/apply": { "post": { "description": "Author the property's cancellation terms — the rule booking resolves into a reservation's frozen cancellation schedule, and the night audit's no-show sweep charges from. Upsert by `code`: a repeated code rewrites that policy in place. Unlike the deposit engine there is no dated succession, because a reservation freezes the resolved money at booking and an edit here can no longer reach a booked stay — which is also Apaleo's contract (\"changing a cancellation policy will not affect existing reservations\"). `tiers` is the ladder, sorted descending by `trigger_offset_hours_before_arrival`; exactly one of `penalty_amount` / `penalty_rate` / `penalty_nights` is set per tier, matching its `penalty_kind`. A non-refundable rate ships `non_refundable = true` with empty tiers. Attach to a rate plan via `rate_plan_requires_cancellation_policy` to outrank the property default.\n\nEffects: create hospitality.cancellation_policy; modify hospitality.cancellation_policy; link hospitality.link.cancellation_policy_at_property.", "operationId": "apply_hospitality_action_set_cancellation_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "applies_to_no_show": { "enum": [ "inherit_last_tier", "separate_no_show_tier", "always_100_percent" ], "title": "How a guest who never arrives is charged", "type": "string" }, "code": { "title": "Policy code — the terms' identity within the property", "type": "string" }, "currency": { "format": "iso-4217", "title": "Currency the penalties are denominated in (ISO 4217)", "type": "string" }, "description": { "title": "Operator-facing description; also the wording a booking freezes", "type": "string" }, "name": { "title": "Display name, as the guest sees it", "type": "string" }, "non_refundable": { "title": "Advance-purchase shape: the whole stay is forfeit from the moment of booking, and `tiers` is ignored", "type": "boolean" }, "notice_window_basis": { "enum": [ "local_property_time", "guest_local_time", "utc" ], "title": "Which clock the notice window is measured on", "type": "string" }, "tiers": { "items": { "properties": { "applies_to": { "enum": [ "cancellation", "no_show", "both" ], "type": "string" }, "penalty_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "penalty_kind": { "enum": [ "absolute", "percent_of_total", "n_nights" ], "type": "string" }, "penalty_nights": { "type": "integer" }, "penalty_rate": { "format": "decimal", "type": "string" }, "trigger_offset_hours_before_arrival": { "type": "integer" } }, "required": [ "trigger_offset_hours_before_arrival", "penalty_kind", "applies_to" ], "type": "object" }, "title": "The penalty ladder (omit for a non-refundable or fully flexible policy)", "type": "array" } }, "required": [ "code", "name", "currency", "non_refundable", "applies_to_no_show", "notice_window_basis" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.cancellation_policy_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.cancellation_policy" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_cancellation_policy:apply" ] } ], "summary": "Set cancellation policy", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_cancellation_policy/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_cancellation_policy` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_cancellation_policy:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_cancellation_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "applies_to_no_show": { "enum": [ "inherit_last_tier", "separate_no_show_tier", "always_100_percent" ], "title": "How a guest who never arrives is charged", "type": "string" }, "code": { "title": "Policy code — the terms' identity within the property", "type": "string" }, "currency": { "format": "iso-4217", "title": "Currency the penalties are denominated in (ISO 4217)", "type": "string" }, "description": { "title": "Operator-facing description; also the wording a booking freezes", "type": "string" }, "name": { "title": "Display name, as the guest sees it", "type": "string" }, "non_refundable": { "title": "Advance-purchase shape: the whole stay is forfeit from the moment of booking, and `tiers` is ignored", "type": "boolean" }, "notice_window_basis": { "enum": [ "local_property_time", "guest_local_time", "utc" ], "title": "Which clock the notice window is measured on", "type": "string" }, "tiers": { "items": { "properties": { "applies_to": { "enum": [ "cancellation", "no_show", "both" ], "type": "string" }, "penalty_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "penalty_kind": { "enum": [ "absolute", "percent_of_total", "n_nights" ], "type": "string" }, "penalty_nights": { "type": "integer" }, "penalty_rate": { "format": "decimal", "type": "string" }, "trigger_offset_hours_before_arrival": { "type": "integer" } }, "required": [ "trigger_offset_hours_before_arrival", "penalty_kind", "applies_to" ], "type": "object" }, "title": "The penalty ladder (omit for a non-refundable or fully flexible policy)", "type": "array" } }, "required": [ "code", "name", "currency", "non_refundable", "applies_to_no_show", "notice_window_basis" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.cancellation_policy_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.cancellation_policy" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set cancellation policy (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_cancellation_policy/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_cancellation_policy`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_cancellation_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "applies_to_no_show": { "enum": [ "inherit_last_tier", "separate_no_show_tier", "always_100_percent" ], "title": "How a guest who never arrives is charged", "type": "string" }, "code": { "title": "Policy code — the terms' identity within the property", "type": "string" }, "currency": { "format": "iso-4217", "title": "Currency the penalties are denominated in (ISO 4217)", "type": "string" }, "description": { "title": "Operator-facing description; also the wording a booking freezes", "type": "string" }, "name": { "title": "Display name, as the guest sees it", "type": "string" }, "non_refundable": { "title": "Advance-purchase shape: the whole stay is forfeit from the moment of booking, and `tiers` is ignored", "type": "boolean" }, "notice_window_basis": { "enum": [ "local_property_time", "guest_local_time", "utc" ], "title": "Which clock the notice window is measured on", "type": "string" }, "tiers": { "items": { "properties": { "applies_to": { "enum": [ "cancellation", "no_show", "both" ], "type": "string" }, "penalty_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "penalty_kind": { "enum": [ "absolute", "percent_of_total", "n_nights" ], "type": "string" }, "penalty_nights": { "type": "integer" }, "penalty_rate": { "format": "decimal", "type": "string" }, "trigger_offset_hours_before_arrival": { "type": "integer" } }, "required": [ "trigger_offset_hours_before_arrival", "penalty_kind", "applies_to" ], "type": "object" }, "title": "The penalty ladder (omit for a non-refundable or fully flexible policy)", "type": "array" } }, "required": [ "code", "name", "currency", "non_refundable", "applies_to_no_show", "notice_window_basis" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set cancellation policy (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_cancellation_policy/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_cancellation_policy` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_cancellation_policy:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_cancellation_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "applies_to_no_show": { "enum": [ "inherit_last_tier", "separate_no_show_tier", "always_100_percent" ], "title": "How a guest who never arrives is charged", "type": "string" }, "code": { "title": "Policy code — the terms' identity within the property", "type": "string" }, "currency": { "format": "iso-4217", "title": "Currency the penalties are denominated in (ISO 4217)", "type": "string" }, "description": { "title": "Operator-facing description; also the wording a booking freezes", "type": "string" }, "name": { "title": "Display name, as the guest sees it", "type": "string" }, "non_refundable": { "title": "Advance-purchase shape: the whole stay is forfeit from the moment of booking, and `tiers` is ignored", "type": "boolean" }, "notice_window_basis": { "enum": [ "local_property_time", "guest_local_time", "utc" ], "title": "Which clock the notice window is measured on", "type": "string" }, "tiers": { "items": { "properties": { "applies_to": { "enum": [ "cancellation", "no_show", "both" ], "type": "string" }, "penalty_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "penalty_kind": { "enum": [ "absolute", "percent_of_total", "n_nights" ], "type": "string" }, "penalty_nights": { "type": "integer" }, "penalty_rate": { "format": "decimal", "type": "string" }, "trigger_offset_hours_before_arrival": { "type": "integer" } }, "required": [ "trigger_offset_hours_before_arrival", "penalty_kind", "applies_to" ], "type": "object" }, "title": "The penalty ladder (omit for a non-refundable or fully flexible policy)", "type": "array" } }, "required": [ "code", "name", "currency", "non_refundable", "applies_to_no_show", "notice_window_basis" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set cancellation policy (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_checkout_satisfaction/apply": { "post": { "description": "Record how satisfied the guest said they were at checkout — hubOS's checkout satisfaction on the quality item — as `satisfaction`, 1 (not at all) to 5 (very). Only once the stay the feedback is about has departed (checked out): refused on feedback about no stay, or about a stay still to come or in house. The same score again writes nothing; another replaces it (the event carries the previous). Emits `guest_feedback.checkout_satisfaction_set`.\n\nEffects: modify hospitality.guest_feedback.", "operationId": "apply_hospitality_action_set_checkout_satisfaction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "satisfaction": { "title": "1 (not at all satisfied) to 5 (very satisfied)", "type": "integer" } }, "required": [ "satisfaction" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.guest_feedback" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_checkout_satisfaction:apply" ] } ], "summary": "Set checkout satisfaction", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.set_checkout_satisfaction/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_checkout_satisfaction` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_checkout_satisfaction:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_checkout_satisfaction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "satisfaction": { "title": "1 (not at all satisfied) to 5 (very satisfied)", "type": "integer" } }, "required": [ "satisfaction" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.guest_feedback" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set checkout satisfaction (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.set_checkout_satisfaction/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_checkout_satisfaction`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_checkout_satisfaction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "satisfaction": { "title": "1 (not at all satisfied) to 5 (very satisfied)", "type": "integer" } }, "required": [ "satisfaction" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set checkout satisfaction (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.set_checkout_satisfaction/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_checkout_satisfaction` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_checkout_satisfaction:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_checkout_satisfaction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "satisfaction": { "title": "1 (not at all satisfied) to 5 (very satisfied)", "type": "integer" } }, "required": [ "satisfaction" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set checkout satisfaction (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.set_credit_limit_overage/apply": { "post": { "description": "Set what the night audit does once an in-house stay's bill has reached what its pending card holds hold — OPERA's credit limit, the authorised total. `off` (the default): nothing beyond the house's top-up rule (`set_hold_top_up`). `hold`: the excess is held as a second hold, as a top-up, even where the top-up rule is off or the excess below its threshold (never past its `max_per_stay`). `charge` — OPERA's CREDIT_LIMIT_OVERAGE_PAYMENTS, which \"charges the total balance of a folio when the balance is equal or higher than the credit limit\": the stay's holds are taken for what the bill owes, and one fresh hold placed for what is left of it plus the rule's allowance, instead of stacking another hold on the guest's card. A refusal (the card, the consent, the processor) is recorded on the stay for the desk.\n\nEffects: modify hospitality.property.", "operationId": "apply_hospitality_action_set_credit_limit_overage", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "mode": { "enum": [ "off", "hold", "charge" ], "title": "off, hold or charge", "type": "string" } }, "required": [ "mode" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.property" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_credit_limit_overage:apply" ] } ], "summary": "Set credit limit overage", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_credit_limit_overage/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_credit_limit_overage` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_credit_limit_overage:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_credit_limit_overage", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "mode": { "enum": [ "off", "hold", "charge" ], "title": "off, hold or charge", "type": "string" } }, "required": [ "mode" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.property" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set credit limit overage (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_credit_limit_overage/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_credit_limit_overage`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_credit_limit_overage", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "mode": { "enum": [ "off", "hold", "charge" ], "title": "off, hold or charge", "type": "string" } }, "required": [ "mode" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set credit limit overage (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_credit_limit_overage/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_credit_limit_overage` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_credit_limit_overage:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_credit_limit_overage", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "mode": { "enum": [ "off", "hold", "charge" ], "title": "off, hold or charge", "type": "string" } }, "required": [ "mode" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set credit limit overage (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_deposit_policy/apply": { "post": { "description": "Author one deposit policy at the property — the rule reservation creation derives `deposit_required_amount` / `deposit_due_at` from, and the night audit's deposit sweep enforces. Same succession contract as `set_tax_rule`: policies sharing a `code` form a non-overlapping timeline — a later effective_from end-dates the open-ended predecessor, a repeated (code, effective_from) replaces in place, a call dated before an existing later policy refuses. `basis` decides the numeric shape: the percent bases require `rate` (in [0, 1]) and forbid the others; `flat` requires `flat_amount`; `nights` requires `nights`. `due_basis` + `due_days` place the due instant (days after booking, or days before arrival); `auto_cancel_on_lapse` decides whether End of Day cancels an unpaid lapsed booking or just records the lapse. Attach to a rate plan via `rate_plan_requires_deposit_policy` to outrank the property default.\n\nEffects: create hospitality.deposit_policy; modify hospitality.deposit_policy; link hospitality.link.deposit_policy_at_property.", "operationId": "apply_hospitality_action_set_deposit_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "auto_cancel_on_lapse": { "title": "End of Day cancels an unpaid lapsed booking (true) or only records the lapse (false)", "type": "boolean" }, "basis": { "enum": [ "flat", "percent_of_stay", "percent_of_first_night", "nights" ], "title": "How the required deposit computes", "type": "string" }, "code": { "title": "Policy code — the rule's identity within the property", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "due_basis": { "enum": [ "days_after_booking", "days_before_arrival" ], "title": "Which anchor the due date is measured from", "type": "string" }, "due_days": { "title": "Day offset from the due anchor (>= 0)", "type": "integer" }, "effective_from": { "format": "date", "title": "First booking date the policy applies (inclusive)", "type": "string" }, "effective_to": { "format": "date", "title": "Last booking date the policy applies (inclusive); omit for open-ended", "type": "string" }, "flat_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount for the flat basis", "type": "object" }, "nights": { "title": "Night count for the nights basis", "type": "integer" }, "rate": { "format": "decimal", "title": "Rate for the percent bases (decimal in [0, 1]; 0.50 = 50%)", "type": "string" } }, "required": [ "code", "basis", "due_basis", "due_days", "auto_cancel_on_lapse", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.deposit_policy_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.deposit_policy" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_deposit_policy:apply" ] } ], "summary": "Set deposit policy", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_deposit_policy/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_deposit_policy` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_deposit_policy:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_deposit_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "auto_cancel_on_lapse": { "title": "End of Day cancels an unpaid lapsed booking (true) or only records the lapse (false)", "type": "boolean" }, "basis": { "enum": [ "flat", "percent_of_stay", "percent_of_first_night", "nights" ], "title": "How the required deposit computes", "type": "string" }, "code": { "title": "Policy code — the rule's identity within the property", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "due_basis": { "enum": [ "days_after_booking", "days_before_arrival" ], "title": "Which anchor the due date is measured from", "type": "string" }, "due_days": { "title": "Day offset from the due anchor (>= 0)", "type": "integer" }, "effective_from": { "format": "date", "title": "First booking date the policy applies (inclusive)", "type": "string" }, "effective_to": { "format": "date", "title": "Last booking date the policy applies (inclusive); omit for open-ended", "type": "string" }, "flat_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount for the flat basis", "type": "object" }, "nights": { "title": "Night count for the nights basis", "type": "integer" }, "rate": { "format": "decimal", "title": "Rate for the percent bases (decimal in [0, 1]; 0.50 = 50%)", "type": "string" } }, "required": [ "code", "basis", "due_basis", "due_days", "auto_cancel_on_lapse", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.deposit_policy_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.deposit_policy" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set deposit policy (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_deposit_policy/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_deposit_policy`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_deposit_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "auto_cancel_on_lapse": { "title": "End of Day cancels an unpaid lapsed booking (true) or only records the lapse (false)", "type": "boolean" }, "basis": { "enum": [ "flat", "percent_of_stay", "percent_of_first_night", "nights" ], "title": "How the required deposit computes", "type": "string" }, "code": { "title": "Policy code — the rule's identity within the property", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "due_basis": { "enum": [ "days_after_booking", "days_before_arrival" ], "title": "Which anchor the due date is measured from", "type": "string" }, "due_days": { "title": "Day offset from the due anchor (>= 0)", "type": "integer" }, "effective_from": { "format": "date", "title": "First booking date the policy applies (inclusive)", "type": "string" }, "effective_to": { "format": "date", "title": "Last booking date the policy applies (inclusive); omit for open-ended", "type": "string" }, "flat_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount for the flat basis", "type": "object" }, "nights": { "title": "Night count for the nights basis", "type": "integer" }, "rate": { "format": "decimal", "title": "Rate for the percent bases (decimal in [0, 1]; 0.50 = 50%)", "type": "string" } }, "required": [ "code", "basis", "due_basis", "due_days", "auto_cancel_on_lapse", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set deposit policy (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_deposit_policy/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_deposit_policy` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_deposit_policy:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_deposit_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "auto_cancel_on_lapse": { "title": "End of Day cancels an unpaid lapsed booking (true) or only records the lapse (false)", "type": "boolean" }, "basis": { "enum": [ "flat", "percent_of_stay", "percent_of_first_night", "nights" ], "title": "How the required deposit computes", "type": "string" }, "code": { "title": "Policy code — the rule's identity within the property", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "due_basis": { "enum": [ "days_after_booking", "days_before_arrival" ], "title": "Which anchor the due date is measured from", "type": "string" }, "due_days": { "title": "Day offset from the due anchor (>= 0)", "type": "integer" }, "effective_from": { "format": "date", "title": "First booking date the policy applies (inclusive)", "type": "string" }, "effective_to": { "format": "date", "title": "Last booking date the policy applies (inclusive); omit for open-ended", "type": "string" }, "flat_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount for the flat basis", "type": "object" }, "nights": { "title": "Night count for the nights basis", "type": "integer" }, "rate": { "format": "decimal", "title": "Rate for the percent bases (decimal in [0, 1]; 0.50 = 50%)", "type": "string" } }, "required": [ "code", "basis", "due_basis", "due_days", "auto_cancel_on_lapse", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set deposit policy (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_device_status/apply": { "post": { "description": "Move a device between `active`, `inactive` (benched — a seasonal terminal in a drawer), and `retired` (terminal state; a retired device cannot come back, register a new one). Only `active` devices may attribute writes. Emits `access.device_status_set.recorded`.\n\nEffects: modify hospitality.device.", "operationId": "apply_hospitality_action_set_device_status", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "status": { "enum": [ "active", "inactive", "retired" ], "title": "New lifecycle status", "type": "string" } }, "required": [ "status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.device" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.device" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_device_status:apply" ] } ], "summary": "Set device status", "tags": [ "access" ] } }, "/v1/actions/hospitality.action.set_device_status/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_device_status` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_device_status:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_device_status", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "status": { "enum": [ "active", "inactive", "retired" ], "title": "New lifecycle status", "type": "string" } }, "required": [ "status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.device" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.device" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set device status (dry-run)", "tags": [ "access" ] } }, "/v1/actions/hospitality.action.set_device_status/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_device_status`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_device_status", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "status": { "enum": [ "active", "inactive", "retired" ], "title": "New lifecycle status", "type": "string" } }, "required": [ "status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.device" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set device status (dry-run)", "tags": [ "access" ] } }, "/v1/actions/hospitality.action.set_device_status/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_device_status` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_device_status:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_device_status", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "status": { "enum": [ "active", "inactive", "retired" ], "title": "New lifecycle status", "type": "string" } }, "required": [ "status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.device" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set device status (rollup delta)", "tags": [ "access" ] } }, "/v1/actions/hospitality.action.set_fnb_open_checks_policy/apply": { "post": { "description": "Set what the night audit does with the house's outlets' guest checks still open on the business date it closes (any check whose `business_date` is that day or earlier). `carry` — the default when unset: the day closes, the checks stay open on their own business date (a check may span dates, as Simphony's do; its lines priced and its revenue reported on the day it opened, its settlement stamped when it happens), the audit emits `fnb.checks_carried` listing them, and the till reads them as `carried`. `refuse`: the audit refuses, naming each outlet and check number, until they are settled — Simphony's opt-in privilege to prevent Start of Day with open checks.\n\nEffects: modify hospitality.property.", "operationId": "apply_hospitality_action_set_fnb_open_checks_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "policy": { "enum": [ "carry", "refuse" ], "title": "carry or refuse", "type": "string" } }, "required": [ "policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.property" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_fnb_open_checks_policy:apply" ] } ], "summary": "Set open-checks policy", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_fnb_open_checks_policy/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_fnb_open_checks_policy` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_fnb_open_checks_policy:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_fnb_open_checks_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "policy": { "enum": [ "carry", "refuse" ], "title": "carry or refuse", "type": "string" } }, "required": [ "policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.property" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set open-checks policy (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_fnb_open_checks_policy/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_fnb_open_checks_policy`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_fnb_open_checks_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "policy": { "enum": [ "carry", "refuse" ], "title": "carry or refuse", "type": "string" } }, "required": [ "policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set open-checks policy (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_fnb_open_checks_policy/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_fnb_open_checks_policy` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_fnb_open_checks_policy:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_fnb_open_checks_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "policy": { "enum": [ "carry", "refuse" ], "title": "carry or refuse", "type": "string" } }, "required": [ "policy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set open-checks policy (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_function_event_counts/apply": { "post": { "description": "Set the expected, guaranteed or set attendance (any subset). The guaranteed number may be lowered only before `guarantee_due_at`; after it, it can only rise — the contract's rule. A count above the space's capacity in the event's setup style is refused. Refused on an `actual` or `cancelled` event.\n\nEffects: modify hospitality.function_event.", "operationId": "apply_hospitality_action_set_function_event_counts", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "expected_count": { "title": "Expected attendance", "type": "integer" }, "guarantee_due_at": { "format": "date-time", "title": "When the guarantee is due", "type": "string" }, "guaranteed_count": { "title": "Guaranteed attendance", "type": "integer" }, "set_count": { "title": "How many the room is set for", "type": "integer" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_event" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.function_event" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_function_event_counts:apply" ] } ], "summary": "Set function event counts", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.set_function_event_counts/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_function_event_counts` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_function_event_counts:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_function_event_counts", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "expected_count": { "title": "Expected attendance", "type": "integer" }, "guarantee_due_at": { "format": "date-time", "title": "When the guarantee is due", "type": "string" }, "guaranteed_count": { "title": "Guaranteed attendance", "type": "integer" }, "set_count": { "title": "How many the room is set for", "type": "integer" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_event" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.function_event" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set function event counts (dry-run)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.set_function_event_counts/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_function_event_counts`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_function_event_counts", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "expected_count": { "title": "Expected attendance", "type": "integer" }, "guarantee_due_at": { "format": "date-time", "title": "When the guarantee is due", "type": "string" }, "guaranteed_count": { "title": "Guaranteed attendance", "type": "integer" }, "set_count": { "title": "How many the room is set for", "type": "integer" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_event" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set function event counts (dry-run)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.set_function_event_counts/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_function_event_counts` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_function_event_counts:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_function_event_counts", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "expected_count": { "title": "Expected attendance", "type": "integer" }, "guarantee_due_at": { "format": "date-time", "title": "When the guarantee is due", "type": "string" }, "guaranteed_count": { "title": "Guaranteed attendance", "type": "integer" }, "set_count": { "title": "How many the room is set for", "type": "integer" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_event" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set function event counts (rollup delta)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.set_green_stay/apply": { "post": { "description": "Set or clear the stay's green stay: the guest declined the day's clean for sustainability (hubOS's leaf, beside and never one of its do-not-disturb states). While set, generate_housekeeping_tasks mints no stayover clean for the stay's room — a shared room only when every guest in house in it declined — and the departure clean, turndown and every other task are untouched. Setting it retires today's generated stayover on the room that nobody has started (skipped, with the reason); clearing it re-mints today's stayover when the house's board has been generated for today (reviving the skipped one in place, through the generator's own key and price), so the room is back on the sheet without a re-run. Today is the house's housekeeping service date (its local calendar day). A manual task is never touched. Refused on a stay that has checked out, did not show or was cancelled; setting the value the stay already carries is a no-op. The flag is not guest PII: the floor sets it through the room's in-house stay. Emits `stay.green_stay_set`.\n\nEffects: modify hospitality.stay; modify hospitality.housekeeping_task; create hospitality.housekeeping_task; link hospitality.link.housekeeping_task_for_room.", "operationId": "apply_hospitality_action_set_green_stay", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "green_stay": { "title": "true when the guest declines the day's clean; false clears it", "type": "boolean" } }, "required": [ "green_stay" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.housekeeping_task_for_room" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.stay", "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_green_stay:apply" ] } ], "summary": "Set green stay", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.set_green_stay/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_green_stay` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_green_stay:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_green_stay", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "green_stay": { "title": "true when the guest declines the day's clean; false clears it", "type": "boolean" } }, "required": [ "green_stay" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.housekeeping_task_for_room" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.stay", "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set green stay (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.set_green_stay/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_green_stay`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_green_stay", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "green_stay": { "title": "true when the guest declines the day's clean; false clears it", "type": "boolean" } }, "required": [ "green_stay" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set green stay (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.set_green_stay/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_green_stay` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_green_stay:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_green_stay", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "green_stay": { "title": "true when the guest declines the day's clean; false clears it", "type": "boolean" } }, "required": [ "green_stay" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set green stay (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.set_guest_feedback_labels/apply": { "post": { "description": "File a piece of guest feedback under the house's labels — hubOS's quality labels on the quality item. `labels` is the whole set, by code (empty clears it): each an active label of the feedback's house; a retired one the feedback already carries may stay, and none may be added. The feedback's `labels` and its `guest_feedback_has_label` edges move together; the same set again writes nothing. Any status — labelling files the case, it does not follow it up. Emits `guest_feedback.labels_set`.\n\nEffects: modify hospitality.guest_feedback; link hospitality.link.guest_feedback_has_label; unlink hospitality.link.guest_feedback_has_label.", "operationId": "apply_hospitality_action_set_guest_feedback_labels", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "labels": { "items": { "type": "string" }, "title": "The label codes, the whole set", "type": "array" } }, "required": [ "labels" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.guest_feedback_has_label" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.guest_feedback" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_guest_feedback_labels:apply" ] } ], "summary": "Set guest feedback labels", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.set_guest_feedback_labels/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_guest_feedback_labels` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_guest_feedback_labels:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_guest_feedback_labels", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "labels": { "items": { "type": "string" }, "title": "The label codes, the whole set", "type": "array" } }, "required": [ "labels" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.guest_feedback_has_label" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.guest_feedback" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set guest feedback labels (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.set_guest_feedback_labels/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_guest_feedback_labels`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_guest_feedback_labels", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "labels": { "items": { "type": "string" }, "title": "The label codes, the whole set", "type": "array" } }, "required": [ "labels" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set guest feedback labels (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.set_guest_feedback_labels/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_guest_feedback_labels` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_guest_feedback_labels:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_guest_feedback_labels", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "labels": { "items": { "type": "string" }, "title": "The label codes, the whole set", "type": "array" } }, "required": [ "labels" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set guest feedback labels (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.set_guest_replies/apply": { "post": { "description": "Switch the property's guest replies on or off — the six `event_named` automations that answer a guest who is waiting: their room is ready (`room_queue.room_ready`), the housekeeping they asked for is done (`housekeeping.task.completed`), the fault they reported is fixed (`work_order.completed`). Three fire `record_guest_message` into the guest's own conversation — the asking message's, or, for a request the desk keyed for their stay, the one they have open at the house — on the channel they last wrote on, and only when there is one. Three write first, through `message_guest`, to a guest who has no conversation open at the house — whose request the desk keyed, or who is queued for a room: by text, else email, to the contact their profile holds; an event answers through one of the two kinds, never both. The first call installs them at the property (in draft when switched off), and a later call installs any the house lacks; `enabled` activates them, `false` pauses them. Off by default: a house that never calls this has none, and installed definitions are ordinary automations the tenant can read, tune while paused (`update_automation`) and archive. Delivery is the messaging adapter's: the kernel records the outbound message, and its creation is what a channel adapter subscribes to. Emits `guest_replies.set.recorded`.\n\nEffects: create hospitality.automation; modify hospitality.automation.", "operationId": "apply_hospitality_action_set_guest_replies", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "enabled": { "title": "Whether the house answers waiting guests automatically", "type": "boolean" } }, "required": [ "enabled" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.automation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_guest_replies:apply" ] } ], "summary": "Set guest replies", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_guest_replies/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_guest_replies` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_guest_replies:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_guest_replies", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "enabled": { "title": "Whether the house answers waiting guests automatically", "type": "boolean" } }, "required": [ "enabled" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.automation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set guest replies (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_guest_replies/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_guest_replies`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_guest_replies", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "enabled": { "title": "Whether the house answers waiting guests automatically", "type": "boolean" } }, "required": [ "enabled" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set guest replies (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_guest_replies/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_guest_replies` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_guest_replies:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_guest_replies", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "enabled": { "title": "Whether the house answers waiting guests automatically", "type": "boolean" } }, "required": [ "enabled" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set guest replies (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_hold_top_up/apply": { "post": { "description": "Set whether the night audit tops up an in-house stay's card hold as its bill grows. On, after each audit the card rail works out, for every in-house stay with a pending hold, OPERA's top-up — the bill's balance, less what the stay's pending holds hold, plus the allowance of the incidental-hold rule the stay's booking matches (for the nights still to come) — and when that excess is more than `threshold` places it as a second hold (`hold_purpose = top_up`) on the card the stay's hold was taken on, off-session (the card must carry the guest's consent to merchant-initiated charges), or raises the hold itself where the card and the account allow incremental authorisation. At most `max_per_stay` top-ups a stay (1 to 10, default 3): each is a hold on the guest's card until check-out. A refusal is recorded on the stay for the desk. Off (`enabled: false`, the default) the audit tops up nothing; `set_credit_limit_overage` still acts once a bill reaches what is held. With `interval_minutes` (60 to 1440) the card rail also plans the house's in-house stays that often between audits — OPERA's scheduler, \"every 60 minutes or more\" — skipping a stay whose last top-up or refusal is inside the interval, and one whose refusal still stands (the card is not asked again before the audit or the desk); 0 or unset (the default), only the audit and the desk's Top up now.\n\nEffects: modify hospitality.property.", "operationId": "apply_hospitality_action_set_hold_top_up", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "enabled": { "title": "Whether the night audit tops holds up", "type": "boolean" }, "interval_minutes": { "title": "How often between audits the card rail plans the top-ups, in minutes (60 to 1440; 0 or unset: at the audit and on the desk's press only)", "type": "integer" }, "max_per_stay": { "title": "The most top-ups for one stay (default 3)", "type": "integer" }, "threshold": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "The smallest excess worth a top-up (required when enabled; 0 tops up any excess)", "type": "object" } }, "required": [ "enabled" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.property" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_hold_top_up:apply" ] } ], "summary": "Set hold top-up", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_hold_top_up/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_hold_top_up` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_hold_top_up:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_hold_top_up", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "enabled": { "title": "Whether the night audit tops holds up", "type": "boolean" }, "interval_minutes": { "title": "How often between audits the card rail plans the top-ups, in minutes (60 to 1440; 0 or unset: at the audit and on the desk's press only)", "type": "integer" }, "max_per_stay": { "title": "The most top-ups for one stay (default 3)", "type": "integer" }, "threshold": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "The smallest excess worth a top-up (required when enabled; 0 tops up any excess)", "type": "object" } }, "required": [ "enabled" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.property" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set hold top-up (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_hold_top_up/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_hold_top_up`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_hold_top_up", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "enabled": { "title": "Whether the night audit tops holds up", "type": "boolean" }, "interval_minutes": { "title": "How often between audits the card rail plans the top-ups, in minutes (60 to 1440; 0 or unset: at the audit and on the desk's press only)", "type": "integer" }, "max_per_stay": { "title": "The most top-ups for one stay (default 3)", "type": "integer" }, "threshold": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "The smallest excess worth a top-up (required when enabled; 0 tops up any excess)", "type": "object" } }, "required": [ "enabled" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set hold top-up (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_hold_top_up/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_hold_top_up` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_hold_top_up:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_hold_top_up", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "enabled": { "title": "Whether the night audit tops holds up", "type": "boolean" }, "interval_minutes": { "title": "How often between audits the card rail plans the top-ups, in minutes (60 to 1440; 0 or unset: at the audit and on the desk's press only)", "type": "integer" }, "max_per_stay": { "title": "The most top-ups for one stay (default 3)", "type": "integer" }, "threshold": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "The smallest excess worth a top-up (required when enabled; 0 tops up any excess)", "type": "object" } }, "required": [ "enabled" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set hold top-up (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_housekeeping_credit_rule/apply": { "post": { "description": "Author what one kind of housekeeping task is worth at the property (OPERA's housekeeping credits, the unit of hubOS's pacing report): `credits` — the workload unit attendants' sheets are balanced in and shift targets are counted in — and optionally `standard_minutes`, what the work should take. Keyed by (`task_type`, `room_type_id`): a call repeating a key at the property replaces that rule in place and revives it if it was retired (the authoring event keeps the history), and an identical restatement writes nothing; omitting `room_type_id` authors the rule for every room type without one of its own. From then on `create_housekeeping_task` and `generate_housekeeping_tasks` stamp the most specific active rule's figures onto each new task; tasks already minted keep theirs, except a generated task still pending, which the next generation run re-prices. Emits `housekeeping_credit_rule.set.recorded`.\n\nEffects: create hospitality.housekeeping_credit_rule; modify hospitality.housekeeping_credit_rule; link hospitality.link.housekeeping_credit_rule_at_property.", "operationId": "apply_hospitality_action_set_housekeeping_credit_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "credits": { "format": "decimal", "title": "Credits one such task is worth (zero or more)", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "room_type_id": { "format": "uuid", "title": "The room type the rule is for; omit for every room type without a rule of its own", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "standard_minutes": { "title": "Minutes the work should take (1 to 1440)", "type": "integer" }, "task_type": { "enum": [ "stayover", "departure", "vacant_pickup", "deep_clean", "turndown", "inspection", "public_area_clean", "public_area_inspection", "minibar", "laundry" ], "title": "The task type the rule prices", "type": "string" } }, "required": [ "task_type", "credits" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.housekeeping_credit_rule_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.housekeeping_credit_rule" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_housekeeping_credit_rule:apply" ] } ], "summary": "Set housekeeping credit rule", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_housekeeping_credit_rule/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_housekeeping_credit_rule` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_housekeeping_credit_rule:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_housekeeping_credit_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "credits": { "format": "decimal", "title": "Credits one such task is worth (zero or more)", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "room_type_id": { "format": "uuid", "title": "The room type the rule is for; omit for every room type without a rule of its own", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "standard_minutes": { "title": "Minutes the work should take (1 to 1440)", "type": "integer" }, "task_type": { "enum": [ "stayover", "departure", "vacant_pickup", "deep_clean", "turndown", "inspection", "public_area_clean", "public_area_inspection", "minibar", "laundry" ], "title": "The task type the rule prices", "type": "string" } }, "required": [ "task_type", "credits" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.housekeeping_credit_rule_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.housekeeping_credit_rule" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set housekeeping credit rule (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_housekeeping_credit_rule/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_housekeeping_credit_rule`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_housekeeping_credit_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "credits": { "format": "decimal", "title": "Credits one such task is worth (zero or more)", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "room_type_id": { "format": "uuid", "title": "The room type the rule is for; omit for every room type without a rule of its own", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "standard_minutes": { "title": "Minutes the work should take (1 to 1440)", "type": "integer" }, "task_type": { "enum": [ "stayover", "departure", "vacant_pickup", "deep_clean", "turndown", "inspection", "public_area_clean", "public_area_inspection", "minibar", "laundry" ], "title": "The task type the rule prices", "type": "string" } }, "required": [ "task_type", "credits" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set housekeeping credit rule (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_housekeeping_credit_rule/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_housekeeping_credit_rule` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_housekeeping_credit_rule:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_housekeeping_credit_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "credits": { "format": "decimal", "title": "Credits one such task is worth (zero or more)", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "room_type_id": { "format": "uuid", "title": "The room type the rule is for; omit for every room type without a rule of its own", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "standard_minutes": { "title": "Minutes the work should take (1 to 1440)", "type": "integer" }, "task_type": { "enum": [ "stayover", "departure", "vacant_pickup", "deep_clean", "turndown", "inspection", "public_area_clean", "public_area_inspection", "minibar", "laundry" ], "title": "The task type the rule prices", "type": "string" } }, "required": [ "task_type", "credits" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set housekeeping credit rule (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_incidental_hold_policy/apply": { "post": { "description": "Author one incidental-hold rule at the property — the card hold `suggest_incidental_hold` derives for a check-in, so the desk pre-fills it instead of typing it. Keyed by `code`: a call repeating an existing code at the property replaces that rule in place (the authoring event keeps the history); a new code mints a rule. `basis` decides how `allowance` is used — `per_night` (allowance × nights), `room_and_per_night` (room total + allowance × nights), `room_plus_flat` (room total + allowance), `flat` (allowance) — OPERA's authorization rules 7, 2, 9 and 5 — and `room` (room total), `room_and_per_person_night` (room total + allowance × persons × nights), `per_person_night` (allowance × persons × nights) and `room_plus_percent` (room total + `percent` of it) — rules 1, 3, 8 and 4. The room total is OPERA's nights × Daily Rate: the booked rate plus the house's room taxes charged on top of it. `guarantee` (OPERA's reservation type), `room_type_ref`, `rate_plan_ref` and `source` narrow the rule; a reservation is served by the active rule every one of whose narrowings it matches, the most specific first in OPERA's precedence — room type, then rate plan, then guarantee, then source — and a rule narrowed by none is the house default. `active: false` retires a rule without deleting it.\n\nEffects: create hospitality.incidental_hold_policy; modify hospitality.incidental_hold_policy; link hospitality.link.incidental_hold_policy_at_property.", "operationId": "apply_hospitality_action_set_incidental_hold_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "active": { "title": "Whether check-ins draw on the rule (default true)", "type": "boolean" }, "allowance": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "The per-night allowance, or the flat amount (non-negative)", "type": "object" }, "basis": { "enum": [ "per_night", "room_and_per_night", "room_plus_flat", "flat", "room", "room_and_per_person_night", "per_person_night", "room_plus_percent" ], "title": "How the suggested hold computes", "type": "string" }, "code": { "title": "Policy code — the rule's identity within the property", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "guarantee": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "title": "The reservation guarantee the rule is for; omit for any", "type": "string" }, "percent": { "format": "decimal", "title": "For room_plus_percent: the percentage of the room total added (10 = 10%)", "type": "string" }, "rate_plan_ref": { "format": "uuid", "title": "The rate plan the rule is for; omit for any", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_ref": { "format": "uuid", "title": "The room type the rule is for; omit for any", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "The booking source the rule is for; omit for any", "type": "string" } }, "required": [ "code", "basis", "allowance" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.incidental_hold_policy_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.incidental_hold_policy" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_incidental_hold_policy:apply" ] } ], "summary": "Set incidental hold policy", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_incidental_hold_policy/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_incidental_hold_policy` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_incidental_hold_policy:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_incidental_hold_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "active": { "title": "Whether check-ins draw on the rule (default true)", "type": "boolean" }, "allowance": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "The per-night allowance, or the flat amount (non-negative)", "type": "object" }, "basis": { "enum": [ "per_night", "room_and_per_night", "room_plus_flat", "flat", "room", "room_and_per_person_night", "per_person_night", "room_plus_percent" ], "title": "How the suggested hold computes", "type": "string" }, "code": { "title": "Policy code — the rule's identity within the property", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "guarantee": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "title": "The reservation guarantee the rule is for; omit for any", "type": "string" }, "percent": { "format": "decimal", "title": "For room_plus_percent: the percentage of the room total added (10 = 10%)", "type": "string" }, "rate_plan_ref": { "format": "uuid", "title": "The rate plan the rule is for; omit for any", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_ref": { "format": "uuid", "title": "The room type the rule is for; omit for any", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "The booking source the rule is for; omit for any", "type": "string" } }, "required": [ "code", "basis", "allowance" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.incidental_hold_policy_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.incidental_hold_policy" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set incidental hold policy (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_incidental_hold_policy/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_incidental_hold_policy`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_incidental_hold_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "active": { "title": "Whether check-ins draw on the rule (default true)", "type": "boolean" }, "allowance": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "The per-night allowance, or the flat amount (non-negative)", "type": "object" }, "basis": { "enum": [ "per_night", "room_and_per_night", "room_plus_flat", "flat", "room", "room_and_per_person_night", "per_person_night", "room_plus_percent" ], "title": "How the suggested hold computes", "type": "string" }, "code": { "title": "Policy code — the rule's identity within the property", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "guarantee": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "title": "The reservation guarantee the rule is for; omit for any", "type": "string" }, "percent": { "format": "decimal", "title": "For room_plus_percent: the percentage of the room total added (10 = 10%)", "type": "string" }, "rate_plan_ref": { "format": "uuid", "title": "The rate plan the rule is for; omit for any", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_ref": { "format": "uuid", "title": "The room type the rule is for; omit for any", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "The booking source the rule is for; omit for any", "type": "string" } }, "required": [ "code", "basis", "allowance" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set incidental hold policy (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_incidental_hold_policy/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_incidental_hold_policy` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_incidental_hold_policy:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_incidental_hold_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "active": { "title": "Whether check-ins draw on the rule (default true)", "type": "boolean" }, "allowance": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "The per-night allowance, or the flat amount (non-negative)", "type": "object" }, "basis": { "enum": [ "per_night", "room_and_per_night", "room_plus_flat", "flat", "room", "room_and_per_person_night", "per_person_night", "room_plus_percent" ], "title": "How the suggested hold computes", "type": "string" }, "code": { "title": "Policy code — the rule's identity within the property", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "guarantee": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "title": "The reservation guarantee the rule is for; omit for any", "type": "string" }, "percent": { "format": "decimal", "title": "For room_plus_percent: the percentage of the room total added (10 = 10%)", "type": "string" }, "rate_plan_ref": { "format": "uuid", "title": "The rate plan the rule is for; omit for any", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_ref": { "format": "uuid", "title": "The room type the rule is for; omit for any", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "The booking source the rule is for; omit for any", "type": "string" } }, "required": [ "code", "basis", "allowance" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set incidental hold policy (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_no_show_posting_rule/apply": { "post": { "description": "Author the property's no-show posting rule for one reservation guarantee — what the night audit posts when it marks such a booking a no-show (OPERA's Post Revenue To No Shows, opt-in): `all_nights` posts every booked night's rate, `first_night` the first night of every room, `deposit_only` forfeits the deposit the house holds (nothing when it holds none), `none` posts nothing. Postings land on the booking's own account through `post_charge` / `forfeit_deposit`, attributed to `outlet_id` (required unless the basis is `none`). Keyed by `guarantee`: a call repeating a guarantee at the property replaces that rule in place (the authoring event keeps the history); omitting it authors the house default for every guarantee without a rule of its own. `active: false` retires a rule without deleting it.\n\nEffects: create hospitality.no_show_posting_rule; modify hospitality.no_show_posting_rule; link hospitality.link.no_show_posting_rule_at_property.", "operationId": "apply_hospitality_action_set_no_show_posting_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "active": { "title": "Whether the audit applies the rule (default true)", "type": "boolean" }, "basis": { "enum": [ "all_nights", "first_night", "deposit_only", "none" ], "title": "What the audit posts for a no-show the rule covers", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "guarantee": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "title": "The reservation guarantee the rule is for; omit for the house default", "type": "string" }, "outlet_id": { "format": "uuid", "title": "Outlet the postings are attributed to (required unless basis is none)", "type": "string", "x-aerandil-references": "hospitality.outlet" } }, "required": [ "basis" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.no_show_posting_rule_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.no_show_posting_rule" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_no_show_posting_rule:apply" ] } ], "summary": "Set no-show posting rule", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_no_show_posting_rule/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_no_show_posting_rule` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_no_show_posting_rule:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_no_show_posting_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "active": { "title": "Whether the audit applies the rule (default true)", "type": "boolean" }, "basis": { "enum": [ "all_nights", "first_night", "deposit_only", "none" ], "title": "What the audit posts for a no-show the rule covers", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "guarantee": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "title": "The reservation guarantee the rule is for; omit for the house default", "type": "string" }, "outlet_id": { "format": "uuid", "title": "Outlet the postings are attributed to (required unless basis is none)", "type": "string", "x-aerandil-references": "hospitality.outlet" } }, "required": [ "basis" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.no_show_posting_rule_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.no_show_posting_rule" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set no-show posting rule (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_no_show_posting_rule/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_no_show_posting_rule`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_no_show_posting_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "active": { "title": "Whether the audit applies the rule (default true)", "type": "boolean" }, "basis": { "enum": [ "all_nights", "first_night", "deposit_only", "none" ], "title": "What the audit posts for a no-show the rule covers", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "guarantee": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "title": "The reservation guarantee the rule is for; omit for the house default", "type": "string" }, "outlet_id": { "format": "uuid", "title": "Outlet the postings are attributed to (required unless basis is none)", "type": "string", "x-aerandil-references": "hospitality.outlet" } }, "required": [ "basis" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set no-show posting rule (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_no_show_posting_rule/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_no_show_posting_rule` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_no_show_posting_rule:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_no_show_posting_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "active": { "title": "Whether the audit applies the rule (default true)", "type": "boolean" }, "basis": { "enum": [ "all_nights", "first_night", "deposit_only", "none" ], "title": "What the audit posts for a no-show the rule covers", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "guarantee": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "title": "The reservation guarantee the rule is for; omit for the house default", "type": "string" }, "outlet_id": { "format": "uuid", "title": "Outlet the postings are attributed to (required unless basis is none)", "type": "string", "x-aerandil-references": "hospitality.outlet" } }, "required": [ "basis" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set no-show posting rule (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_outlet_meal_periods/apply": { "post": { "description": "Set when each meal runs at the outlet, replacing the whole list: each period a `daypart`, a `start_time` and `end_time` in 24-hour HH:MM on the house's wall clock, and optionally its `days_of_week` (absent = every day), so a weekday breakfast and a weekend one are two rows. An `end_time` before the start runs past midnight and belongs to the day it started; the same start and end is a whole day from that time. Periods may not overlap, and that is refused naming both; gaps are allowed. `open_check` stamps a live check with the period in force unless it is told otherwise; in a gap the check carries no meal, and none is ever refused for its hours. An empty list clears the hours. The same list again changes nothing.\n\nEffects: modify hospitality.outlet.", "operationId": "apply_hospitality_action_set_outlet_meal_periods", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "meal_periods": { "items": { "properties": { "daypart": { "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "type": "string" }, "days_of_week": { "items": { "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "type": "string" }, "type": "array" }, "end_time": { "type": "string" }, "start_time": { "type": "string" } }, "required": [ "daypart", "start_time", "end_time" ], "type": "object" }, "title": "The outlet's meal periods, whole; empty clears them", "type": "array" } }, "required": [ "meal_periods" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.outlet" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.outlet" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_outlet_meal_periods:apply" ] } ], "summary": "Set meal periods", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.set_outlet_meal_periods/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_outlet_meal_periods` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_outlet_meal_periods:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_outlet_meal_periods", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "meal_periods": { "items": { "properties": { "daypart": { "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "type": "string" }, "days_of_week": { "items": { "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "type": "string" }, "type": "array" }, "end_time": { "type": "string" }, "start_time": { "type": "string" } }, "required": [ "daypart", "start_time", "end_time" ], "type": "object" }, "title": "The outlet's meal periods, whole; empty clears them", "type": "array" } }, "required": [ "meal_periods" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.outlet" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.outlet" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set meal periods (dry-run)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.set_outlet_meal_periods/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_outlet_meal_periods`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_outlet_meal_periods", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "meal_periods": { "items": { "properties": { "daypart": { "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "type": "string" }, "days_of_week": { "items": { "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "type": "string" }, "type": "array" }, "end_time": { "type": "string" }, "start_time": { "type": "string" } }, "required": [ "daypart", "start_time", "end_time" ], "type": "object" }, "title": "The outlet's meal periods, whole; empty clears them", "type": "array" } }, "required": [ "meal_periods" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.outlet" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set meal periods (dry-run)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.set_outlet_meal_periods/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_outlet_meal_periods` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_outlet_meal_periods:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_outlet_meal_periods", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "meal_periods": { "items": { "properties": { "daypart": { "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "type": "string" }, "days_of_week": { "items": { "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "type": "string" }, "type": "array" }, "end_time": { "type": "string" }, "start_time": { "type": "string" } }, "required": [ "daypart", "start_time", "end_time" ], "type": "object" }, "title": "The outlet's meal periods, whole; empty clears them", "type": "array" } }, "required": [ "meal_periods" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.outlet" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set meal periods (rollup delta)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.set_payment_request_messaging/apply": { "post": { "description": "Turn pay links to the guest on or off at a house. On, every payment request's pay link — the desk's request or the booking automation's — is sent to the booking's guest as soon as the card rail has minted it: by email, or by SMS when the profile holds no email, refused (and noted on the request) when the guest asked for erasure or texted STOP. Off, the desk sends the link itself. A request whose link was minted while it was off is not sent later. `reuse_terms` sets the words the pay page shows the guest about keeping their card for later charges (an empty string puts the card rail's default back; omitted, they are unchanged).\n\nEffects: modify hospitality.property.", "operationId": "apply_hospitality_action_set_payment_request_messaging", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "enabled": { "title": "Send pay links to the guest", "type": "boolean" }, "reuse_terms": { "title": "Pay page card terms (at most 1,200 characters)", "type": "string" } }, "required": [ "enabled" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.property" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_payment_request_messaging:apply" ] } ], "summary": "Set payment request messaging", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_payment_request_messaging/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_payment_request_messaging` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_payment_request_messaging:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_payment_request_messaging", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "enabled": { "title": "Send pay links to the guest", "type": "boolean" }, "reuse_terms": { "title": "Pay page card terms (at most 1,200 characters)", "type": "string" } }, "required": [ "enabled" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.property" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set payment request messaging (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_payment_request_messaging/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_payment_request_messaging`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_payment_request_messaging", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "enabled": { "title": "Send pay links to the guest", "type": "boolean" }, "reuse_terms": { "title": "Pay page card terms (at most 1,200 characters)", "type": "string" } }, "required": [ "enabled" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set payment request messaging (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_payment_request_messaging/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_payment_request_messaging` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_payment_request_messaging:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_payment_request_messaging", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "enabled": { "title": "Send pay links to the guest", "type": "boolean" }, "reuse_terms": { "title": "Pay page card terms (at most 1,200 characters)", "type": "string" } }, "required": [ "enabled" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set payment request messaging (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_post_stay_charging/apply": { "post": { "description": "Set how many calendar days after departure a charge found later — the minibar, damage, laundry — may still be posted to the departed stay's bill and taken from its card (`days`, 0 to 14; 0 turns it off), counting the departure's own date in the house's time zone as the first. On, check-out keeps the stay's pending card hold that lasts longest for the window — until the window's end or the hold's own deadline, whichever comes first — and releases the others, and the window closes at the house's midnight after its last day: 1 keeps the bill chargeable until the end of the departure's date, as OPERA's Post Stay Charging does. Off (the default), check-out releases every hold the stay still has. Applies to departures from now on; a window already open keeps its end.\n\nEffects: modify hospitality.property.", "operationId": "apply_hospitality_action_set_post_stay_charging", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "days": { "title": "Calendar days the window lasts, the departure's date first (0 = off)", "type": "integer" } }, "required": [ "days" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.property" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_post_stay_charging:apply" ] } ], "summary": "Set post-stay charging", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_post_stay_charging/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_post_stay_charging` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_post_stay_charging:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_post_stay_charging", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "days": { "title": "Calendar days the window lasts, the departure's date first (0 = off)", "type": "integer" } }, "required": [ "days" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.property" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set post-stay charging (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_post_stay_charging/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_post_stay_charging`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_post_stay_charging", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "days": { "title": "Calendar days the window lasts, the departure's date first (0 = off)", "type": "integer" } }, "required": [ "days" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set post-stay charging (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_post_stay_charging/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_post_stay_charging` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_post_stay_charging:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_post_stay_charging", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "days": { "title": "Calendar days the window lasts, the departure's date first (0 = off)", "type": "integer" } }, "required": [ "days" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set post-stay charging (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_posting_rules/apply": { "post": { "description": "The desk's posting rules for an in-house stay — what an outlet's till may put on the guest's bill. `no_post: true` is OPERA's NOPOST: every room charge and charge-to-key to the stay is refused (`no_post`). `credit_limit` is the most the stay's bill may reach, the room still to come included — OPERA's credit limit for the guest's payment method; absent, it is cleared. A till's posting is held to the greater of the limit and what the stay's live card holds hold, less the stay's bills' balance and the room still due for the nights to come; a posting that would pass it is refused (`no_credit`). A stay with neither a limit nor a hold has no credit rule (no_post is the house's lever there). An override on the payment (`override_reason`) taken under a manager's own session lets either refusal through, and is recorded on the payment with the session's staff member as its authoriser. Never moves anything already posted. Re-setting the same rules is a no-op. Emits `fnb.posting_rules_set` with the reason.\n\nEffects: modify hospitality.stay.", "operationId": "apply_hospitality_action_set_posting_rules", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "credit_limit": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "The most the stay's bill may reach, the room to come included (absent: cleared); zero or more, in the house's currency", "type": "object" }, "no_post": { "title": "Refuse every outlet posting to the stay", "type": "boolean" }, "reason": { "title": "Why the desk set the rules (kept on the event)", "type": "string" } }, "required": [ "no_post" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.stay" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_posting_rules:apply" ] } ], "summary": "Set posting rules", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.set_posting_rules/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_posting_rules` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_posting_rules:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_posting_rules", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "credit_limit": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "The most the stay's bill may reach, the room to come included (absent: cleared); zero or more, in the house's currency", "type": "object" }, "no_post": { "title": "Refuse every outlet posting to the stay", "type": "boolean" }, "reason": { "title": "Why the desk set the rules (kept on the event)", "type": "string" } }, "required": [ "no_post" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.stay" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set posting rules (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.set_posting_rules/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_posting_rules`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_posting_rules", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "credit_limit": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "The most the stay's bill may reach, the room to come included (absent: cleared); zero or more, in the house's currency", "type": "object" }, "no_post": { "title": "Refuse every outlet posting to the stay", "type": "boolean" }, "reason": { "title": "Why the desk set the rules (kept on the event)", "type": "string" } }, "required": [ "no_post" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set posting rules (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.set_posting_rules/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_posting_rules` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_posting_rules:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_posting_rules", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "credit_limit": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "The most the stay's bill may reach, the room to come included (absent: cleared); zero or more, in the house's currency", "type": "object" }, "no_post": { "title": "Refuse every outlet posting to the stay", "type": "boolean" }, "reason": { "title": "Why the desk set the rules (kept on the event)", "type": "string" } }, "required": [ "no_post" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set posting rules (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.set_public_area_reader_code/apply": { "post": { "description": "Set the code the area's QR / NFC reader carries — what the handset scans to open the area's card and its checklist (hubOS's common-areas QR) — or clear it when `reader_code` is absent or blank. Unique within the property across rooms and areas alike, one scan, one place: a code a room or another area of the house already carries is refused, and two first writes of one code — to an area or a room — queue on the house's reader-code lock, so the second reads the first. A retired area takes no code. Setting the code the area already carries is a no-op. The object search finds the area by it (an `eq` filter on `reader_code`, narrowed to the house). Emits `public_area.reader_code_set`.\n\nEffects: modify hospitality.public_area.", "operationId": "apply_hospitality_action_set_public_area_reader_code", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reader_code": { "title": "The code (trimmed; absent or blank clears it)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.public_area" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.public_area" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_public_area_reader_code:apply" ] } ], "summary": "Set public area reader code", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.set_public_area_reader_code/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_public_area_reader_code` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_public_area_reader_code:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_public_area_reader_code", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reader_code": { "title": "The code (trimmed; absent or blank clears it)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.public_area" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.public_area" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set public area reader code (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.set_public_area_reader_code/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_public_area_reader_code`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_public_area_reader_code", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reader_code": { "title": "The code (trimmed; absent or blank clears it)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.public_area" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set public area reader code (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.set_public_area_reader_code/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_public_area_reader_code` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_public_area_reader_code:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_public_area_reader_code", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reader_code": { "title": "The code (trimmed; absent or blank clears it)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.public_area" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set public area reader code (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.set_rate_restriction/apply": { "post": { "description": "Author a sell restriction — stop-sell (`closed`), closed-to-arrival, closed-to-departure, MinLOS / MaxLOS — over a date range, scoped to a room type, a rate plan, or the pair (at least one must be given; restrictions compose as a conjunction with whatever else covers the date). At least one constraint must be set: an all-open restriction is refused rather than stored as noise. Opening a window back up is `clear_rate_restrictions`, which splices existing rows rather than stacking an 'open' override, or `lift_rate_restriction`, which takes one authored row off the board and keeps it as history. `posted_at` is business time (defaults to now); `external_ref` is a replay key — a second set carrying the same ref lands on the existing row, lifted or not, and writes nothing.\n\nEffects: create hospitality.rate_restriction; link hospitality.link.room_type_has_restriction; link hospitality.link.rate_plan_has_restriction.", "operationId": "apply_hospitality_action_set_rate_restriction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "closed": { "title": "Hard stop-sell (defaults to false)", "type": "boolean" }, "closed_to_arrival": { "title": "Closed to arrival (defaults to false)", "type": "boolean" }, "closed_to_departure": { "title": "Closed to departure (defaults to false)", "type": "boolean" }, "end_date": { "format": "date", "title": "End date (inclusive)", "type": "string" }, "external_ref": { "title": "Replay key from the authoring source; a repeat with the same ref is a no-op on the existing row", "type": "string" }, "max_length_of_stay": { "title": "Maximum length of stay (nights)", "type": "integer" }, "min_length_of_stay": { "title": "Minimum length of stay (nights)", "type": "integer" }, "posted_at": { "format": "date-time", "title": "Business time the restriction was posted (defaults to now; must not be in the future)", "type": "string" }, "property_id": { "format": "uuid", "title": "Property the restriction row is scoped to", "type": "string", "x-aerandil-references": "hospitality.property" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan scope (at least one of room_type_id / rate_plan_id)", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type scope (at least one of room_type_id / rate_plan_id)", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "start_date": { "format": "date", "title": "Start date", "type": "string" } }, "required": [ "property_id", "start_date", "end_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.room_type_has_restriction", "hospitality.link.rate_plan_has_restriction" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.rate_restriction" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_rate_restriction:apply" ] } ], "summary": "Set rate restriction", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.set_rate_restriction/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_rate_restriction` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_rate_restriction:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_rate_restriction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "closed": { "title": "Hard stop-sell (defaults to false)", "type": "boolean" }, "closed_to_arrival": { "title": "Closed to arrival (defaults to false)", "type": "boolean" }, "closed_to_departure": { "title": "Closed to departure (defaults to false)", "type": "boolean" }, "end_date": { "format": "date", "title": "End date (inclusive)", "type": "string" }, "external_ref": { "title": "Replay key from the authoring source; a repeat with the same ref is a no-op on the existing row", "type": "string" }, "max_length_of_stay": { "title": "Maximum length of stay (nights)", "type": "integer" }, "min_length_of_stay": { "title": "Minimum length of stay (nights)", "type": "integer" }, "posted_at": { "format": "date-time", "title": "Business time the restriction was posted (defaults to now; must not be in the future)", "type": "string" }, "property_id": { "format": "uuid", "title": "Property the restriction row is scoped to", "type": "string", "x-aerandil-references": "hospitality.property" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan scope (at least one of room_type_id / rate_plan_id)", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type scope (at least one of room_type_id / rate_plan_id)", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "start_date": { "format": "date", "title": "Start date", "type": "string" } }, "required": [ "property_id", "start_date", "end_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.room_type_has_restriction", "hospitality.link.rate_plan_has_restriction" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.rate_restriction" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set rate restriction (dry-run)", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.set_rate_restriction/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_rate_restriction`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_rate_restriction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "closed": { "title": "Hard stop-sell (defaults to false)", "type": "boolean" }, "closed_to_arrival": { "title": "Closed to arrival (defaults to false)", "type": "boolean" }, "closed_to_departure": { "title": "Closed to departure (defaults to false)", "type": "boolean" }, "end_date": { "format": "date", "title": "End date (inclusive)", "type": "string" }, "external_ref": { "title": "Replay key from the authoring source; a repeat with the same ref is a no-op on the existing row", "type": "string" }, "max_length_of_stay": { "title": "Maximum length of stay (nights)", "type": "integer" }, "min_length_of_stay": { "title": "Minimum length of stay (nights)", "type": "integer" }, "posted_at": { "format": "date-time", "title": "Business time the restriction was posted (defaults to now; must not be in the future)", "type": "string" }, "property_id": { "format": "uuid", "title": "Property the restriction row is scoped to", "type": "string", "x-aerandil-references": "hospitality.property" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan scope (at least one of room_type_id / rate_plan_id)", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type scope (at least one of room_type_id / rate_plan_id)", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "start_date": { "format": "date", "title": "Start date", "type": "string" } }, "required": [ "property_id", "start_date", "end_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set rate restriction (dry-run)", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.set_rate_restriction/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_rate_restriction` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_rate_restriction:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_rate_restriction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "closed": { "title": "Hard stop-sell (defaults to false)", "type": "boolean" }, "closed_to_arrival": { "title": "Closed to arrival (defaults to false)", "type": "boolean" }, "closed_to_departure": { "title": "Closed to departure (defaults to false)", "type": "boolean" }, "end_date": { "format": "date", "title": "End date (inclusive)", "type": "string" }, "external_ref": { "title": "Replay key from the authoring source; a repeat with the same ref is a no-op on the existing row", "type": "string" }, "max_length_of_stay": { "title": "Maximum length of stay (nights)", "type": "integer" }, "min_length_of_stay": { "title": "Minimum length of stay (nights)", "type": "integer" }, "posted_at": { "format": "date-time", "title": "Business time the restriction was posted (defaults to now; must not be in the future)", "type": "string" }, "property_id": { "format": "uuid", "title": "Property the restriction row is scoped to", "type": "string", "x-aerandil-references": "hospitality.property" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan scope (at least one of room_type_id / rate_plan_id)", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type scope (at least one of room_type_id / rate_plan_id)", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "start_date": { "format": "date", "title": "Start date", "type": "string" } }, "required": [ "property_id", "start_date", "end_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set rate restriction (rollup delta)", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.set_rates/apply": { "post": { "description": "Author per-date prices for a (rate_plan, room_type, occupancy) tuple over a date range, optionally masked to days of the week. Upserts the canonical `rate_per_night` rows: an existing row for a matching (rate_plan, room_type, occupancy, date) cell is re-priced in place, a missing one is minted and linked — re-applying the same pattern is an idempotent no-op. The amount must be in the rate plan's currency, and a bar_grid rate plan requires `bar_anchor_amount` (the anchor the derivation resolves against is date-varying and lives on the row).\n\nEffects: create hospitality.rate_per_night; modify hospitality.rate_per_night; link hospitality.link.rate_plan_has_rate_per_night; link hospitality.link.room_type_has_rate_per_night.\n\nStep-up when `bar_anchor_amount` is given: a person (a `User` principal) needs a fresh desk step-up proof — Moving the BAR anchor re-prices every rate derived from it — or the call is refused `403 step_up_required` before anything runs. Re-enter the passcode at `POST /v1/desk/sessions/{id}/passcode` and retry. Machine principals are not gated.", "operationId": "apply_hospitality_action_set_rates", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount per night", "type": "object" }, "bar_anchor_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "BAR anchor (required for bar_grid rate plans)", "type": "object" }, "days_of_week": { "items": { "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "type": "string" }, "title": "Days of week the pattern applies to (defaults to all seven)", "type": "array" }, "end_date": { "format": "date", "title": "End date (inclusive)", "type": "string" }, "inclusive_of_tax": { "title": "Amount is inclusive of tax", "type": "boolean" }, "occupancy": { "title": "Occupancy (adult count this price applies to)", "type": "integer" }, "property_id": { "format": "uuid", "title": "Property the priced rows are scoped to (plans and room types can be brand-standard; prices are always per-property)", "type": "string", "x-aerandil-references": "hospitality.property" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "start_date": { "format": "date", "title": "Start date", "type": "string" } }, "required": [ "property_id", "rate_plan_id", "room_type_id", "start_date", "end_date", "occupancy", "amount" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.rate_plan_has_rate_per_night", "hospitality.link.room_type_has_rate_per_night" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.rate_per_night" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "403": { "description": "`step_up_required` — a person applied this without a fresh desk step-up proof; nothing ran." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_rates:apply" ] } ], "summary": "Set rates", "tags": [ "distribution" ], "x-aerandil-step-up": { "reason": "Moving the BAR anchor re-prices every rate derived from it", "when": { "kind": "param_present", "param": "bar_anchor_amount" } } } }, "/v1/actions/hospitality.action.set_rates/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_rates` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_rates:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_rates", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount per night", "type": "object" }, "bar_anchor_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "BAR anchor (required for bar_grid rate plans)", "type": "object" }, "days_of_week": { "items": { "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "type": "string" }, "title": "Days of week the pattern applies to (defaults to all seven)", "type": "array" }, "end_date": { "format": "date", "title": "End date (inclusive)", "type": "string" }, "inclusive_of_tax": { "title": "Amount is inclusive of tax", "type": "boolean" }, "occupancy": { "title": "Occupancy (adult count this price applies to)", "type": "integer" }, "property_id": { "format": "uuid", "title": "Property the priced rows are scoped to (plans and room types can be brand-standard; prices are always per-property)", "type": "string", "x-aerandil-references": "hospitality.property" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "start_date": { "format": "date", "title": "Start date", "type": "string" } }, "required": [ "property_id", "rate_plan_id", "room_type_id", "start_date", "end_date", "occupancy", "amount" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.rate_plan_has_rate_per_night", "hospitality.link.room_type_has_rate_per_night" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.rate_per_night" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set rates (dry-run)", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.set_rates/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_rates`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_rates", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount per night", "type": "object" }, "bar_anchor_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "BAR anchor (required for bar_grid rate plans)", "type": "object" }, "days_of_week": { "items": { "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "type": "string" }, "title": "Days of week the pattern applies to (defaults to all seven)", "type": "array" }, "end_date": { "format": "date", "title": "End date (inclusive)", "type": "string" }, "inclusive_of_tax": { "title": "Amount is inclusive of tax", "type": "boolean" }, "occupancy": { "title": "Occupancy (adult count this price applies to)", "type": "integer" }, "property_id": { "format": "uuid", "title": "Property the priced rows are scoped to (plans and room types can be brand-standard; prices are always per-property)", "type": "string", "x-aerandil-references": "hospitality.property" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "start_date": { "format": "date", "title": "Start date", "type": "string" } }, "required": [ "property_id", "rate_plan_id", "room_type_id", "start_date", "end_date", "occupancy", "amount" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set rates (dry-run)", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.set_rates/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_rates` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_rates:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_rates", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount per night", "type": "object" }, "bar_anchor_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "BAR anchor (required for bar_grid rate plans)", "type": "object" }, "days_of_week": { "items": { "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "type": "string" }, "title": "Days of week the pattern applies to (defaults to all seven)", "type": "array" }, "end_date": { "format": "date", "title": "End date (inclusive)", "type": "string" }, "inclusive_of_tax": { "title": "Amount is inclusive of tax", "type": "boolean" }, "occupancy": { "title": "Occupancy (adult count this price applies to)", "type": "integer" }, "property_id": { "format": "uuid", "title": "Property the priced rows are scoped to (plans and room types can be brand-standard; prices are always per-property)", "type": "string", "x-aerandil-references": "hospitality.property" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "start_date": { "format": "date", "title": "Start date", "type": "string" } }, "required": [ "property_id", "rate_plan_id", "room_type_id", "start_date", "end_date", "occupancy", "amount" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set rates (rollup delta)", "tags": [ "distribution" ] } }, "/v1/actions/hospitality.action.set_request_urgency_window/apply": { "post": { "description": "Set the house's own \"soon\": how many minutes before its due time a request reads as `soon` on the housekeeping_requests read and the handset's card (`property.request_soon_minutes`, 1 to 720; unset, the kernel's 30). The same value again is a no-op.\n\nEffects: modify hospitality.property.", "operationId": "apply_hospitality_action_set_request_urgency_window", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "soon_minutes": { "title": "Minutes ahead within which a request reads as soon (1 to 720)", "type": "integer" } }, "required": [ "soon_minutes" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.property" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_request_urgency_window:apply" ] } ], "summary": "Set request urgency window", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_request_urgency_window/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_request_urgency_window` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_request_urgency_window:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_request_urgency_window", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "soon_minutes": { "title": "Minutes ahead within which a request reads as soon (1 to 720)", "type": "integer" } }, "required": [ "soon_minutes" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.property" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set request urgency window (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_request_urgency_window/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_request_urgency_window`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_request_urgency_window", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "soon_minutes": { "title": "Minutes ahead within which a request reads as soon (1 to 720)", "type": "integer" } }, "required": [ "soon_minutes" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set request urgency window (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_request_urgency_window/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_request_urgency_window` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_request_urgency_window:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_request_urgency_window", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "soon_minutes": { "title": "Minutes ahead within which a request reads as soon (1 to 720)", "type": "integer" } }, "required": [ "soon_minutes" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set request urgency window (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_room_housekeeping_status/apply": { "post": { "description": "The attendant's one-call report (OPERA's putRoomRelatedStatus): set the cleaning status, the physically observed occupancy, and/or the observed occupant count — at least one. Observed occupancy and person counts compare against system truth on the spot: a mismatch raises a skip / sleep / person room_discrepancy, and a corrected observation auto-resolves what an erroneous one opened. Setting the cleaning status on a room under an active out-of-order block refuses (release decides the status the room re-enters in); observations alone are always allowed.\n\nEffects: modify hospitality.room; create hospitality.room_discrepancy; modify hospitality.room_discrepancy; link hospitality.link.room_discrepancy_for_room.", "operationId": "apply_hospitality_action_set_room_housekeeping_status", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "housekeeping_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "New cleaning status", "type": "string" }, "observed_at": { "format": "date-time", "title": "When the observation was made (defaults to now)", "type": "string" }, "observed_occupancy": { "enum": [ "vacant", "occupied" ], "title": "Occupancy the attendant physically found", "type": "string" }, "observed_persons": { "title": "Occupant count the attendant physically found", "type": "integer" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.room_discrepancy_for_room" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.room", "hospitality.room_discrepancy" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_room_housekeeping_status:apply" ] } ], "summary": "Set room housekeeping status", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.set_room_housekeeping_status/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_room_housekeeping_status` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_room_housekeeping_status:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_room_housekeeping_status", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "housekeeping_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "New cleaning status", "type": "string" }, "observed_at": { "format": "date-time", "title": "When the observation was made (defaults to now)", "type": "string" }, "observed_occupancy": { "enum": [ "vacant", "occupied" ], "title": "Occupancy the attendant physically found", "type": "string" }, "observed_persons": { "title": "Occupant count the attendant physically found", "type": "integer" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.room_discrepancy_for_room" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.room", "hospitality.room_discrepancy" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set room housekeeping status (dry-run)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.set_room_housekeeping_status/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_room_housekeeping_status`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_room_housekeeping_status", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "housekeeping_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "New cleaning status", "type": "string" }, "observed_at": { "format": "date-time", "title": "When the observation was made (defaults to now)", "type": "string" }, "observed_occupancy": { "enum": [ "vacant", "occupied" ], "title": "Occupancy the attendant physically found", "type": "string" }, "observed_persons": { "title": "Occupant count the attendant physically found", "type": "integer" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set room housekeeping status (dry-run)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.set_room_housekeeping_status/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_room_housekeeping_status` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_room_housekeeping_status:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_room_housekeeping_status", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "housekeeping_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "New cleaning status", "type": "string" }, "observed_at": { "format": "date-time", "title": "When the observation was made (defaults to now)", "type": "string" }, "observed_occupancy": { "enum": [ "vacant", "occupied" ], "title": "Occupancy the attendant physically found", "type": "string" }, "observed_persons": { "title": "Occupant count the attendant physically found", "type": "integer" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set room housekeeping status (rollup delta)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.set_room_reader_code/apply": { "post": { "description": "Set the code the room's QR / NFC reader carries — what the handset scans at the door to open the room's card (hubOS's `hk_reader_code`) — or clear it when `reader_code` is absent or blank. Unique within the property: a code another room — or a public area (2026-10-14) — of the house already carries is refused, and two first writes of one code queue on a per-house lock, so the second reads the first. Setting the code the room already carries is a no-op. The object search finds a room by it (an `eq` filter on `reader_code`, narrowed to the house). Emits `room.reader_code_set`.\n\nEffects: modify hospitality.room.", "operationId": "apply_hospitality_action_set_room_reader_code", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reader_code": { "title": "The code (trimmed; absent or blank clears it)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.room" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_room_reader_code:apply" ] } ], "summary": "Set room reader code", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.set_room_reader_code/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_room_reader_code` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_room_reader_code:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_room_reader_code", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reader_code": { "title": "The code (trimmed; absent or blank clears it)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.room" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set room reader code (dry-run)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.set_room_reader_code/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_room_reader_code`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_room_reader_code", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reader_code": { "title": "The code (trimmed; absent or blank clears it)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set room reader code (dry-run)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.set_room_reader_code/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_room_reader_code` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_room_reader_code:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_room_reader_code", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reader_code": { "title": "The code (trimmed; absent or blank clears it)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set room reader code (rollup delta)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.set_sca_chase/apply": { "post": { "description": "Set the house's rule for a guest whose bank asks them to confirm a charge or a hold the card rail tried without them (Stripe's `authentication_required`): `enabled` sends the guest a page to confirm it on, `hours` is how long they have (1 to 168, default 24) and `reminders` how many reminders go before the deadline, spread evenly across it (0 to 3, default 1 — one at half-time). Past the deadline the house is told (`payment.authentication_overdue`). Off (the default), the pending state and its deadline are still recorded, and the desk sends the page itself. Applies to authentications asked for from now on; one already pending keeps its deadline.\n\nEffects: modify hospitality.property.", "operationId": "apply_hospitality_action_set_sca_chase", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "enabled": { "title": "Send the guest the page, remind them, tell the house at the deadline", "type": "boolean" }, "hours": { "title": "Hours the guest has to confirm (default 24)", "type": "integer" }, "reminders": { "title": "Reminders before the deadline (default 1)", "type": "integer" } }, "required": [ "enabled" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.property" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_sca_chase:apply" ] } ], "summary": "Set SCA chase", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_sca_chase/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_sca_chase` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_sca_chase:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_sca_chase", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "enabled": { "title": "Send the guest the page, remind them, tell the house at the deadline", "type": "boolean" }, "hours": { "title": "Hours the guest has to confirm (default 24)", "type": "integer" }, "reminders": { "title": "Reminders before the deadline (default 1)", "type": "integer" } }, "required": [ "enabled" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.property" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set SCA chase (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_sca_chase/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_sca_chase`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_sca_chase", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "enabled": { "title": "Send the guest the page, remind them, tell the house at the deadline", "type": "boolean" }, "hours": { "title": "Hours the guest has to confirm (default 24)", "type": "integer" }, "reminders": { "title": "Reminders before the deadline (default 1)", "type": "integer" } }, "required": [ "enabled" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set SCA chase (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_sca_chase/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_sca_chase` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_sca_chase:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_sca_chase", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "enabled": { "title": "Send the guest the page, remind them, tell the house at the deadline", "type": "boolean" }, "hours": { "title": "Hours the guest has to confirm (default 24)", "type": "integer" }, "reminders": { "title": "Reminders before the deadline (default 1)", "type": "integer" } }, "required": [ "enabled" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set SCA chase (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_shift_credit_target/apply": { "post": { "description": "Set the housekeeping credits an attendant is expected to clean on an open shift — OPERA's per-sheet maximum credits, hubOS's pacing target. The pacing report (`housekeeping_pacing`) counts the attendant's completed credits against it. Omit `credit_target` to clear it. Refuses a closed or voided shift: the target is the shift's plan, and a closed shift is history. Also settable at `clock_in`. The target the shift already has writes nothing. Emits `labour.shift_target.set` when it moves.\n\nEffects: modify hospitality.staff_shift.", "operationId": "apply_hospitality_action_set_shift_credit_target", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "credit_target": { "format": "decimal", "title": "Credits expected this shift (zero or more); omit to clear", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_shift" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.staff_shift" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_shift_credit_target:apply" ] } ], "summary": "Set shift credit target", "tags": [ "labour" ] } }, "/v1/actions/hospitality.action.set_shift_credit_target/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_shift_credit_target` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_shift_credit_target:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_shift_credit_target", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "credit_target": { "format": "decimal", "title": "Credits expected this shift (zero or more); omit to clear", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_shift" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.staff_shift" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set shift credit target (dry-run)", "tags": [ "labour" ] } }, "/v1/actions/hospitality.action.set_shift_credit_target/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_shift_credit_target`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_shift_credit_target", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "credit_target": { "format": "decimal", "title": "Credits expected this shift (zero or more); omit to clear", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_shift" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set shift credit target (dry-run)", "tags": [ "labour" ] } }, "/v1/actions/hospitality.action.set_shift_credit_target/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_shift_credit_target` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_shift_credit_target:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_shift_credit_target", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "credit_target": { "format": "decimal", "title": "Credits expected this shift (zero or more); omit to clear", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_shift" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set shift credit target (rollup delta)", "tags": [ "labour" ] } }, "/v1/actions/hospitality.action.set_staff_push_topics/apply": { "post": { "description": "Choose the push topics a staff member's handset is nudged for (hubOS's notification topics): cleaning_tasks (a task assigned or reclaimed to me, my task made urgent), faults (a work order assigned or reclaimed to me), urgent_faults (a blocking or safety fault raised or escalated at my house — to its engineers), postponed_faults (a fault postponed — to its assignee and the house's engineers) and delegated_faults (a fault handed to my role at my house). Omit `topics` to go back to the default — cleaning_tasks and faults; the fault topics are heard only when named. A staff member's session sets only its own; a supervisor sets any colleague's at their house. Emits `staff_member.push_topics.set`.\n\nEffects: modify hospitality.staff_member.", "operationId": "apply_hospitality_action_set_staff_push_topics", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "topics": { "items": { "enum": [ "cleaning_tasks", "faults", "urgent_faults", "postponed_faults", "delegated_faults", "stock" ], "type": "string" }, "title": "The topics to hear (omit for the default)", "type": "array" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.staff_member" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_staff_push_topics:apply" ] } ], "summary": "Set staff push topics", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.set_staff_push_topics/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_staff_push_topics` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_staff_push_topics:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_staff_push_topics", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "topics": { "items": { "enum": [ "cleaning_tasks", "faults", "urgent_faults", "postponed_faults", "delegated_faults", "stock" ], "type": "string" }, "title": "The topics to hear (omit for the default)", "type": "array" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.staff_member" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set staff push topics (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.set_staff_push_topics/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_staff_push_topics`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_staff_push_topics", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "topics": { "items": { "enum": [ "cleaning_tasks", "faults", "urgent_faults", "postponed_faults", "delegated_faults", "stock" ], "type": "string" }, "title": "The topics to hear (omit for the default)", "type": "array" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set staff push topics (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.set_staff_push_topics/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_staff_push_topics` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_staff_push_topics:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_staff_push_topics", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "topics": { "items": { "enum": [ "cleaning_tasks", "faults", "urgent_faults", "postponed_faults", "delegated_faults", "stock" ], "type": "string" }, "title": "The topics to hear (omit for the default)", "type": "array" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set staff push topics (rollup delta)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.set_staff_sort_preference/apply": { "post": { "description": "Set a staff member's own order for one board (hubOS: each user keeps their own pacing-report sort) — the same keys set_board_sort_pattern takes, held to the same rules; omit `keys` to clear it and read the house's pattern again. Stored on the member (`sort_preferences`, one entry per board) and returned by `board_sort` ahead of the house's pattern. A staff member's session sets only its own; a supervisor (housekeeping or front-office supervisor, manager on duty, general manager, owner) sets any colleague's at their house. The same order again writes nothing. Emits `staff_member.sort_preference.set`.\n\nEffects: modify hospitality.staff_member.", "operationId": "apply_hospitality_action_set_staff_sort_preference", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "board": { "enum": [ "housekeeping_sheet", "housekeeping_rack", "work_orders", "pacing" ], "title": "The board the preference orders", "type": "string" }, "keys": { "items": { "properties": { "direction": { "enum": [ "asc", "desc" ], "type": "string" }, "key": { "enum": [ "priority", "room_number", "floor", "task_type", "status", "due_at", "credits", "arrival_time", "departure_time", "pending_credits", "target_percent", "name" ], "type": "string" }, "values": { "items": { "type": "string" }, "type": "array" } }, "required": [ "key", "direction" ], "type": "object" }, "title": "Sort keys", "type": "array" } }, "required": [ "board" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.staff_member" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_staff_sort_preference:apply" ] } ], "summary": "Set staff sort preference", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.set_staff_sort_preference/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_staff_sort_preference` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_staff_sort_preference:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_staff_sort_preference", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "board": { "enum": [ "housekeeping_sheet", "housekeeping_rack", "work_orders", "pacing" ], "title": "The board the preference orders", "type": "string" }, "keys": { "items": { "properties": { "direction": { "enum": [ "asc", "desc" ], "type": "string" }, "key": { "enum": [ "priority", "room_number", "floor", "task_type", "status", "due_at", "credits", "arrival_time", "departure_time", "pending_credits", "target_percent", "name" ], "type": "string" }, "values": { "items": { "type": "string" }, "type": "array" } }, "required": [ "key", "direction" ], "type": "object" }, "title": "Sort keys", "type": "array" } }, "required": [ "board" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.staff_member" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set staff sort preference (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.set_staff_sort_preference/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_staff_sort_preference`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_staff_sort_preference", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "board": { "enum": [ "housekeeping_sheet", "housekeeping_rack", "work_orders", "pacing" ], "title": "The board the preference orders", "type": "string" }, "keys": { "items": { "properties": { "direction": { "enum": [ "asc", "desc" ], "type": "string" }, "key": { "enum": [ "priority", "room_number", "floor", "task_type", "status", "due_at", "credits", "arrival_time", "departure_time", "pending_credits", "target_percent", "name" ], "type": "string" }, "values": { "items": { "type": "string" }, "type": "array" } }, "required": [ "key", "direction" ], "type": "object" }, "title": "Sort keys", "type": "array" } }, "required": [ "board" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set staff sort preference (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.set_staff_sort_preference/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_staff_sort_preference` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_staff_sort_preference:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_staff_sort_preference", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "board": { "enum": [ "housekeeping_sheet", "housekeeping_rack", "work_orders", "pacing" ], "title": "The board the preference orders", "type": "string" }, "keys": { "items": { "properties": { "direction": { "enum": [ "asc", "desc" ], "type": "string" }, "key": { "enum": [ "priority", "room_number", "floor", "task_type", "status", "due_at", "credits", "arrival_time", "departure_time", "pending_credits", "target_percent", "name" ], "type": "string" }, "values": { "items": { "type": "string" }, "type": "array" } }, "required": [ "key", "direction" ], "type": "object" }, "title": "Sort keys", "type": "array" } }, "required": [ "board" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set staff sort preference (rollup delta)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.set_stock_reorder_point/apply": { "post": { "description": "Set the level at or below which this store's stock of a material is reordered (OPERA's par), or clear it (no reorder_point). A movement that takes the level from above the point to at or below it emits `stock_level.below_reorder_point`. Mints the level when the store holds none of it yet. Setting the point it already has is a no-op.\n\nEffects: create hospitality.stock_level; modify hospitality.stock_level; link hospitality.link.stock_level_for_material; link hospitality.link.stock_level_in_store.", "operationId": "apply_hospitality_action_set_stock_reorder_point", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "material_id": { "format": "uuid", "title": "The material", "type": "string", "x-aerandil-references": "hospitality.material" }, "reorder_point": { "format": "decimal", "title": "The reorder point, in the material's unit (absent clears it)", "type": "string" } }, "required": [ "material_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_store" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.stock_level_for_material", "hospitality.link.stock_level_in_store" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.stock_level" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_stock_reorder_point:apply" ] } ], "summary": "Set stock reorder point", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.set_stock_reorder_point/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_stock_reorder_point` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_stock_reorder_point:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_stock_reorder_point", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "material_id": { "format": "uuid", "title": "The material", "type": "string", "x-aerandil-references": "hospitality.material" }, "reorder_point": { "format": "decimal", "title": "The reorder point, in the material's unit (absent clears it)", "type": "string" } }, "required": [ "material_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_store" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.stock_level_for_material", "hospitality.link.stock_level_in_store" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.stock_level" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set stock reorder point (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.set_stock_reorder_point/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_stock_reorder_point`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_stock_reorder_point", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "material_id": { "format": "uuid", "title": "The material", "type": "string", "x-aerandil-references": "hospitality.material" }, "reorder_point": { "format": "decimal", "title": "The reorder point, in the material's unit (absent clears it)", "type": "string" } }, "required": [ "material_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_store" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set stock reorder point (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.set_stock_reorder_point/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_stock_reorder_point` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_stock_reorder_point:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_stock_reorder_point", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "material_id": { "format": "uuid", "title": "The material", "type": "string", "x-aerandil-references": "hospitality.material" }, "reorder_point": { "format": "decimal", "title": "The reorder point, in the material's unit (absent clears it)", "type": "string" } }, "required": [ "material_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_store" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set stock reorder point (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.set_tax_exemption/apply": { "post": { "description": "Record that a booking is exempt from named tax codes — a government or diplomatic guest with a certificate on file (OPERA's tax-exempt profile, held on the booking). From now on every tax line derived for the booking (room nights, day use, forfeited deposits, cancellation and no-show charges) skips a rule whose code is listed; postings already made keep their tax. A booking carries at most one exemption in force: a second call replaces it (the old one is revoked and stays as the trail). Each code must name a tax rule the house has authored.\n\nEffects: create hospitality.tax_exemption; modify hospitality.tax_exemption; link hospitality.link.reservation_has_tax_exemption.", "operationId": "apply_hospitality_action_set_tax_exemption", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "description": { "title": "Operator-facing note", "type": "string" }, "exempt_codes": { "items": { "type": "string" }, "title": "The tax rule codes the booking is exempt from (at least one)", "type": "array" }, "reason": { "enum": [ "government", "diplomatic", "international_organisation", "other" ], "title": "Why the booking is exempt", "type": "string" }, "reference": { "title": "The exemption certificate or authority reference", "type": "string" } }, "required": [ "reason", "reference", "exempt_codes" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.reservation_has_tax_exemption" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.tax_exemption" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_tax_exemption:apply" ] } ], "summary": "Set tax exemption", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.set_tax_exemption/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_tax_exemption` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_tax_exemption:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_tax_exemption", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "description": { "title": "Operator-facing note", "type": "string" }, "exempt_codes": { "items": { "type": "string" }, "title": "The tax rule codes the booking is exempt from (at least one)", "type": "array" }, "reason": { "enum": [ "government", "diplomatic", "international_organisation", "other" ], "title": "Why the booking is exempt", "type": "string" }, "reference": { "title": "The exemption certificate or authority reference", "type": "string" } }, "required": [ "reason", "reference", "exempt_codes" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.reservation_has_tax_exemption" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.tax_exemption" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set tax exemption (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.set_tax_exemption/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_tax_exemption`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_tax_exemption", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "description": { "title": "Operator-facing note", "type": "string" }, "exempt_codes": { "items": { "type": "string" }, "title": "The tax rule codes the booking is exempt from (at least one)", "type": "array" }, "reason": { "enum": [ "government", "diplomatic", "international_organisation", "other" ], "title": "Why the booking is exempt", "type": "string" }, "reference": { "title": "The exemption certificate or authority reference", "type": "string" } }, "required": [ "reason", "reference", "exempt_codes" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set tax exemption (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.set_tax_exemption/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_tax_exemption` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_tax_exemption:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_tax_exemption", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "description": { "title": "Operator-facing note", "type": "string" }, "exempt_codes": { "items": { "type": "string" }, "title": "The tax rule codes the booking is exempt from (at least one)", "type": "array" }, "reason": { "enum": [ "government", "diplomatic", "international_organisation", "other" ], "title": "Why the booking is exempt", "type": "string" }, "reference": { "title": "The exemption certificate or authority reference", "type": "string" } }, "required": [ "reason", "reference", "exempt_codes" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set tax exemption (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.set_tax_rule/apply": { "post": { "description": "Author one tax rule at the property — the config the night audit derives `tax_application` lines from. Rules sharing a `code` form a non-overlapping succession timeline: a call whose effective_from lands after the current open-ended rule end-dates that predecessor at effective_from − 1 day and mints the successor (the Mews validity-interval model — a rate change is never an in-place edit of history); a call repeating an existing rule's (code, effective_from) replaces that row in place (converging replay / mis-key correction); a call dated before an existing later rule for the same code refuses — successions are authored forward. `basis` decides the shape: `percent` requires `rate` (in [0, 1]) and forbids `flat_amount`; `flat_per_night` and `per_person_per_night` require `flat_amount` and forbid `rate`. `inclusive` decides whether the tax lives inside the posted amount (VAT carve-out) or on top of it (US-style add-on). The rule targets exactly one of `bucket`, `system_charge_kind` or `tax_class` (the VAT class an F&B item class names — a percent rule; the till rings every rule in force for a line's class): a forfeited deposit, cancellation fee or no-show charge is taxed only by a percent, inclusive rule targeting its kind, so a house in a jurisdiction that taxes retained payments (the UK) authors them and one that does not (Austria) authors none. The succession timeline is per (code, target), so one `VAT` code can cover rooms and the retained payments alike. `reduced_after_nights` + `reduced_value_share` on a percent rooms rule is the UK 28-day rule. The emitted authoring event is the permanent who-changed-what-tax-when trail.\n\nEffects: create hospitality.tax_rule; modify hospitality.tax_rule; link hospitality.link.tax_rule_at_property.", "operationId": "apply_hospitality_action_set_tax_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults_only": { "title": "per_person_per_night only: count adults, not children", "type": "boolean" }, "basis": { "enum": [ "percent", "flat_per_night", "per_person_per_night" ], "title": "How the tax computes", "type": "string" }, "bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "USALI bucket whose charges this rule taxes (or give system_charge_kind)", "type": "string" }, "code": { "title": "Tax code — the rule's identity within the property", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "effective_from": { "format": "date", "title": "First business date the rule applies (inclusive)", "type": "string" }, "effective_to": { "format": "date", "title": "Last business date the rule applies (inclusive); omit for open-ended", "type": "string" }, "flat_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount per room night (flat_per_night) or per guest per night (per_person_per_night)", "type": "object" }, "inclusive": { "title": "Tax lives inside the posted amount (true) or on top (false)", "type": "boolean" }, "jurisdiction": { "title": "Taxing jurisdiction", "type": "string" }, "rate": { "format": "decimal", "title": "Rate for percent rules (decimal in [0, 1]; 0.10 = 10%)", "type": "string" }, "reduced_after_nights": { "title": "Percent rooms rules only: tax a reduced value from the night after this many nights of a continuous stay (28 for the UK)", "type": "integer" }, "reduced_value_share": { "format": "decimal", "title": "The share of a long-stay night still taxed (0.20 for the UK)", "type": "string" }, "system_charge_kind": { "enum": [ "forfeited_deposit", "cancellation_fee", "no_show_fee", "no_show_revenue" ], "title": "The retained payment this rule taxes (or give bucket)", "type": "string" }, "tax_class": { "title": "The F&B tax class this rule taxes (or give bucket / system_charge_kind)", "type": "string" } }, "required": [ "code", "jurisdiction", "basis", "inclusive", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.tax_rule_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.tax_rule" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_tax_rule:apply" ] } ], "summary": "Set tax rule", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_tax_rule/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_tax_rule` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_tax_rule:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_tax_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults_only": { "title": "per_person_per_night only: count adults, not children", "type": "boolean" }, "basis": { "enum": [ "percent", "flat_per_night", "per_person_per_night" ], "title": "How the tax computes", "type": "string" }, "bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "USALI bucket whose charges this rule taxes (or give system_charge_kind)", "type": "string" }, "code": { "title": "Tax code — the rule's identity within the property", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "effective_from": { "format": "date", "title": "First business date the rule applies (inclusive)", "type": "string" }, "effective_to": { "format": "date", "title": "Last business date the rule applies (inclusive); omit for open-ended", "type": "string" }, "flat_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount per room night (flat_per_night) or per guest per night (per_person_per_night)", "type": "object" }, "inclusive": { "title": "Tax lives inside the posted amount (true) or on top (false)", "type": "boolean" }, "jurisdiction": { "title": "Taxing jurisdiction", "type": "string" }, "rate": { "format": "decimal", "title": "Rate for percent rules (decimal in [0, 1]; 0.10 = 10%)", "type": "string" }, "reduced_after_nights": { "title": "Percent rooms rules only: tax a reduced value from the night after this many nights of a continuous stay (28 for the UK)", "type": "integer" }, "reduced_value_share": { "format": "decimal", "title": "The share of a long-stay night still taxed (0.20 for the UK)", "type": "string" }, "system_charge_kind": { "enum": [ "forfeited_deposit", "cancellation_fee", "no_show_fee", "no_show_revenue" ], "title": "The retained payment this rule taxes (or give bucket)", "type": "string" }, "tax_class": { "title": "The F&B tax class this rule taxes (or give bucket / system_charge_kind)", "type": "string" } }, "required": [ "code", "jurisdiction", "basis", "inclusive", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.tax_rule_at_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.tax_rule" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set tax rule (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_tax_rule/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_tax_rule`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_tax_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults_only": { "title": "per_person_per_night only: count adults, not children", "type": "boolean" }, "basis": { "enum": [ "percent", "flat_per_night", "per_person_per_night" ], "title": "How the tax computes", "type": "string" }, "bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "USALI bucket whose charges this rule taxes (or give system_charge_kind)", "type": "string" }, "code": { "title": "Tax code — the rule's identity within the property", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "effective_from": { "format": "date", "title": "First business date the rule applies (inclusive)", "type": "string" }, "effective_to": { "format": "date", "title": "Last business date the rule applies (inclusive); omit for open-ended", "type": "string" }, "flat_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount per room night (flat_per_night) or per guest per night (per_person_per_night)", "type": "object" }, "inclusive": { "title": "Tax lives inside the posted amount (true) or on top (false)", "type": "boolean" }, "jurisdiction": { "title": "Taxing jurisdiction", "type": "string" }, "rate": { "format": "decimal", "title": "Rate for percent rules (decimal in [0, 1]; 0.10 = 10%)", "type": "string" }, "reduced_after_nights": { "title": "Percent rooms rules only: tax a reduced value from the night after this many nights of a continuous stay (28 for the UK)", "type": "integer" }, "reduced_value_share": { "format": "decimal", "title": "The share of a long-stay night still taxed (0.20 for the UK)", "type": "string" }, "system_charge_kind": { "enum": [ "forfeited_deposit", "cancellation_fee", "no_show_fee", "no_show_revenue" ], "title": "The retained payment this rule taxes (or give bucket)", "type": "string" }, "tax_class": { "title": "The F&B tax class this rule taxes (or give bucket / system_charge_kind)", "type": "string" } }, "required": [ "code", "jurisdiction", "basis", "inclusive", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set tax rule (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_tax_rule/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_tax_rule` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_tax_rule:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_tax_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults_only": { "title": "per_person_per_night only: count adults, not children", "type": "boolean" }, "basis": { "enum": [ "percent", "flat_per_night", "per_person_per_night" ], "title": "How the tax computes", "type": "string" }, "bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "USALI bucket whose charges this rule taxes (or give system_charge_kind)", "type": "string" }, "code": { "title": "Tax code — the rule's identity within the property", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "effective_from": { "format": "date", "title": "First business date the rule applies (inclusive)", "type": "string" }, "effective_to": { "format": "date", "title": "Last business date the rule applies (inclusive); omit for open-ended", "type": "string" }, "flat_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Amount per room night (flat_per_night) or per guest per night (per_person_per_night)", "type": "object" }, "inclusive": { "title": "Tax lives inside the posted amount (true) or on top (false)", "type": "boolean" }, "jurisdiction": { "title": "Taxing jurisdiction", "type": "string" }, "rate": { "format": "decimal", "title": "Rate for percent rules (decimal in [0, 1]; 0.10 = 10%)", "type": "string" }, "reduced_after_nights": { "title": "Percent rooms rules only: tax a reduced value from the night after this many nights of a continuous stay (28 for the UK)", "type": "integer" }, "reduced_value_share": { "format": "decimal", "title": "The share of a long-stay night still taxed (0.20 for the UK)", "type": "string" }, "system_charge_kind": { "enum": [ "forfeited_deposit", "cancellation_fee", "no_show_fee", "no_show_revenue" ], "title": "The retained payment this rule taxes (or give bucket)", "type": "string" }, "tax_class": { "title": "The F&B tax class this rule taxes (or give bucket / system_charge_kind)", "type": "string" } }, "required": [ "code", "jurisdiction", "basis", "inclusive", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set tax rule (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_waitlist_offer_messaging/apply": { "post": { "description": "Turn the waitlist's guest half on or off at a house. On, every waitlist offer (the desk's or the matcher's) is texted to the guest, or emailed when the profile holds no mobile number, with a link to claim it; off, the desk tells the guest itself. The claim link is `claim_url_base` with the offer's token appended (the kernel's own page is `/v1/waitlist-claims/`); without one the offer asks the guest to reply or call. The base is an https URL with no query or fragment (plain http only to a loopback dev host); a missing trailing slash is added.\n\nEffects: modify hospitality.property.", "operationId": "apply_hospitality_action_set_waitlist_offer_messaging", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "claim_url_base": { "title": "Where the claim link points; the token is appended", "type": "string" }, "enabled": { "title": "Send waitlist offers to the guest", "type": "boolean" } }, "required": [ "enabled" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.property" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_waitlist_offer_messaging:apply" ] } ], "summary": "Set waitlist offer messaging", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_waitlist_offer_messaging/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_waitlist_offer_messaging` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_waitlist_offer_messaging:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_waitlist_offer_messaging", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "claim_url_base": { "title": "Where the claim link points; the token is appended", "type": "string" }, "enabled": { "title": "Send waitlist offers to the guest", "type": "boolean" } }, "required": [ "enabled" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.property" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set waitlist offer messaging (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_waitlist_offer_messaging/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_waitlist_offer_messaging`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_waitlist_offer_messaging", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "claim_url_base": { "title": "Where the claim link points; the token is appended", "type": "string" }, "enabled": { "title": "Send waitlist offers to the guest", "type": "boolean" } }, "required": [ "enabled" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set waitlist offer messaging (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_waitlist_offer_messaging/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_waitlist_offer_messaging` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_waitlist_offer_messaging:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_waitlist_offer_messaging", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "claim_url_base": { "title": "Where the claim link points; the token is appended", "type": "string" }, "enabled": { "title": "Send waitlist offers to the guest", "type": "boolean" } }, "required": [ "enabled" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set waitlist offer messaging (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.set_worker_group_members/apply": { "post": { "description": "Set who is in the group: `member_ids` is the whole membership — staff members missing from it leave the group, new ones join, and an empty list empties it. Every member works at the group's house (a staff member held above the house — a brand's, a tenant's — may join). The same membership again writes nothing. Refuses a retired group. Work already assigned to the group stays the group's: a member who leaves can no longer start it. Emits `worker_group.members_set` with who joined and who left.\n\nEffects: link hospitality.link.worker_group_has_member; unlink hospitality.link.worker_group_has_member.", "operationId": "apply_hospitality_action_set_worker_group_members", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "member_ids": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "title": "The staff members in the group, all of them", "type": "array" } }, "required": [ "member_ids" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.worker_group" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.worker_group_has_member" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.set_worker_group_members:apply" ] } ], "summary": "Set worker group members", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.set_worker_group_members/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_set_worker_group_members` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.set_worker_group_members:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_set_worker_group_members", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "member_ids": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "title": "The staff members in the group, all of them", "type": "array" } }, "required": [ "member_ids" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.worker_group" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.worker_group_has_member" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Set worker group members (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.set_worker_group_members/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_set_worker_group_members`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_set_worker_group_members", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "member_ids": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "title": "The staff members in the group, all of them", "type": "array" } }, "required": [ "member_ids" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.worker_group" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Set worker group members (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.set_worker_group_members/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_set_worker_group_members` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.set_worker_group_members:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_set_worker_group_members", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "member_ids": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "title": "The staff members in the group, all of them", "type": "array" } }, "required": [ "member_ids" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.worker_group" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Set worker group members (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.settle_appointment/apply": { "post": { "description": "Resolve the money on a completed appointment — settle_check's twin. The amount due is the snapshotted price plus gratuity. `tender = room_charge` requires `folio_id` and atomically posts one aggregated spa charge to the folio (bucket = the outlet's usali_department, health_club_spa fallback; charge_at_outlet linked) plus the appointment_settled_to_folio link, emitting `charge.posted.recorded` — the §9.1 fold input. Other tenders stamp `tender` + `settlement_reference`; their revenue reaches the signals tier through the enriched `spa.appointment_settled` event (outlet, bucket, amount, business day) rather than a folio charge — a walk-in's card payment clears through the POS/PSP, not a guest ledger, so no folio is minted for day-spa trade. The charge decomposes like post_charge's: `amount` is the treatment revenue, `gratuity` its own figure (a voluntary tip is a pass-through, not department revenue under USALI), and the folio debit is their sum. Business time: `settled_at` defaults to now; the charge's posted_at and the business day derive from it. A zero-due appointment (fully comped) settles with tender = comp. Re-settling a settled appointment is a no-op.\n\nEffects: modify hospitality.appointment; create hospitality.charge; link hospitality.link.folio_has_charge; link hospitality.link.charge_at_outlet; link hospitality.link.appointment_settled_to_folio; modify hospitality.folio.", "operationId": "apply_hospitality_action_settle_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "folio_id": { "format": "uuid", "title": "Folio to receive the room charge (required for tender = room_charge)", "type": "string", "x-aerandil-references": "hospitality.folio" }, "gratuity": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Gratuity", "type": "object" }, "settled_at": { "format": "date-time", "title": "When the appointment settled — business time, not record time (defaults to now)", "type": "string" }, "settlement_reference": { "title": "PSP / drawer / platform reference for non-room tenders", "type": "string" }, "tender": { "enum": [ "room_charge", "cash", "card", "comp", "external", "charge_to_key" ], "title": "Settlement tender (required unless the amount due is zero)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_charge", "hospitality.link.charge_at_outlet", "hospitality.link.appointment_settled_to_folio" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.appointment", "hospitality.charge", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.settle_appointment:apply" ] } ], "summary": "Settle appointment", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.settle_appointment/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_settle_appointment` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.settle_appointment:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_settle_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "folio_id": { "format": "uuid", "title": "Folio to receive the room charge (required for tender = room_charge)", "type": "string", "x-aerandil-references": "hospitality.folio" }, "gratuity": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Gratuity", "type": "object" }, "settled_at": { "format": "date-time", "title": "When the appointment settled — business time, not record time (defaults to now)", "type": "string" }, "settlement_reference": { "title": "PSP / drawer / platform reference for non-room tenders", "type": "string" }, "tender": { "enum": [ "room_charge", "cash", "card", "comp", "external", "charge_to_key" ], "title": "Settlement tender (required unless the amount due is zero)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_charge", "hospitality.link.charge_at_outlet", "hospitality.link.appointment_settled_to_folio" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified", "created" ] }, "object_type": { "enum": [ "hospitality.appointment", "hospitality.charge", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Settle appointment (dry-run)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.settle_appointment/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_settle_appointment`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_settle_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "folio_id": { "format": "uuid", "title": "Folio to receive the room charge (required for tender = room_charge)", "type": "string", "x-aerandil-references": "hospitality.folio" }, "gratuity": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Gratuity", "type": "object" }, "settled_at": { "format": "date-time", "title": "When the appointment settled — business time, not record time (defaults to now)", "type": "string" }, "settlement_reference": { "title": "PSP / drawer / platform reference for non-room tenders", "type": "string" }, "tender": { "enum": [ "room_charge", "cash", "card", "comp", "external", "charge_to_key" ], "title": "Settlement tender (required unless the amount due is zero)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Settle appointment (dry-run)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.settle_appointment/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_settle_appointment` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.settle_appointment:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_settle_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "folio_id": { "format": "uuid", "title": "Folio to receive the room charge (required for tender = room_charge)", "type": "string", "x-aerandil-references": "hospitality.folio" }, "gratuity": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Gratuity", "type": "object" }, "settled_at": { "format": "date-time", "title": "When the appointment settled — business time, not record time (defaults to now)", "type": "string" }, "settlement_reference": { "title": "PSP / drawer / platform reference for non-room tenders", "type": "string" }, "tender": { "enum": [ "room_charge", "cash", "card", "comp", "external", "charge_to_key" ], "title": "Settlement tender (required unless the amount due is zero)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Settle appointment (rollup delta)", "tags": [ "spa" ] } }, "/v1/actions/hospitality.action.settle_check/apply": { "post": { "description": "Close an open check by paying its whole balance with one tender — the convenience over `add_check_payment`, which it records one payment through: `amount` = the check's `balance_due`, `gratuity` the payment's tip, `settlement_reference` its `psp_reference`, `settled_at` its `paid_at`, and `folio_id`, `reservation_id`, `guest_id` and `credential_token` bound exactly as `add_check_payment` binds them — a room charge names its reservation here too, and a charge-to-key its tapped key — and a room charge consumes the stay's package allowance exactly as `add_check_payment`'s does. Every line must be fulfilled, voided, or comped. A check with nothing due (everything voided / comped, or already paid by earlier payments) settles with no tender and no payment. The gratuity rides any tender here — it is the check's discretionary service charge collected with the tender, which a replayed history carries on cash too. A seated table flips to dirty. A room charge or charge-to-key is held to the stay's posting rules, with a signed-in manager's override (`override_reason`), exactly as `add_check_payment` holds it. Re-settling an already-settled check is a no-op.\n\nEffects: create hospitality.check_payment; link hospitality.link.check_payment_on_check; link hospitality.link.check_payment_to_folio; modify hospitality.guest_check; create hospitality.charge; create hospitality.tax_application; link hospitality.link.folio_has_charge; link hospitality.link.charge_at_outlet; link hospitality.link.charge_has_tax_application; link hospitality.link.check_payment_posted_charge; link hospitality.link.check_settled_to_folio; link hospitality.link.charge_via_credential; modify hospitality.folio; modify hospitality.service_table; create hospitality.check_receipt; link hospitality.link.receipt_for_check; create hospitality.package_component_consumption; modify hospitality.package_sale; link hospitality.link.package_sale_has_consumption; link hospitality.link.consumption_for_charge; link hospitality.link.charge_attributed_to_package_sale; link hospitality.link.charge_attributed_to_package_component; link hospitality.link.consumption_for_check_payment.", "operationId": "apply_hospitality_action_settle_check", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "authorised_by": { "format": "uuid", "title": "Confirms the overriding manager (optional; with override_reason): must be the staff member signed in — the override's authoriser is always the session's own, never one named here", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "credential_token": { "title": "The tapped room key's token (required for charge_to_key)", "type": "string" }, "folio_id": { "format": "uuid", "title": "Folio to receive the room charge (required for room_charge)", "type": "string", "x-aerandil-references": "hospitality.folio" }, "gratuity": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Gratuity — the payment's tip", "type": "object" }, "guest_id": { "format": "uuid", "title": "The guest who signed for a room charge — the reservation's guest", "type": "string", "x-aerandil-references": "hospitality.person" }, "override_reason": { "title": "Override the stay's no-post or credit refusal, and why (room_charge and charge_to_key) — taken under a manager's own session: an F&B manager, a front-office supervisor, the manager on duty, the general manager or the owner, active at the check's house", "type": "string" }, "reservation_id": { "format": "uuid", "title": "The reservation the room-charge folio is a window of (required for room_charge)", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "settled_at": { "format": "date-time", "title": "When the check settled — business time, not record time (defaults to now)", "type": "string" }, "settlement_reference": { "title": "The processor's reference for the tender (the payment's psp_reference)", "type": "string" }, "tender": { "enum": [ "room_charge", "cash", "card", "comp", "external", "charge_to_key" ], "title": "Settlement tender (required unless nothing is due)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.check_payment_on_check", "hospitality.link.check_payment_to_folio", "hospitality.link.folio_has_charge", "hospitality.link.charge_at_outlet", "hospitality.link.charge_has_tax_application", "hospitality.link.check_payment_posted_charge", "hospitality.link.check_settled_to_folio", "hospitality.link.charge_via_credential", "hospitality.link.receipt_for_check", "hospitality.link.package_sale_has_consumption", "hospitality.link.consumption_for_charge", "hospitality.link.charge_attributed_to_package_sale", "hospitality.link.charge_attributed_to_package_component", "hospitality.link.consumption_for_check_payment" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.check_payment", "hospitality.guest_check", "hospitality.charge", "hospitality.tax_application", "hospitality.folio", "hospitality.service_table", "hospitality.check_receipt", "hospitality.package_component_consumption", "hospitality.package_sale" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.settle_check:apply" ] } ], "summary": "Settle check", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.settle_check/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_settle_check` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.settle_check:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_settle_check", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "authorised_by": { "format": "uuid", "title": "Confirms the overriding manager (optional; with override_reason): must be the staff member signed in — the override's authoriser is always the session's own, never one named here", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "credential_token": { "title": "The tapped room key's token (required for charge_to_key)", "type": "string" }, "folio_id": { "format": "uuid", "title": "Folio to receive the room charge (required for room_charge)", "type": "string", "x-aerandil-references": "hospitality.folio" }, "gratuity": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Gratuity — the payment's tip", "type": "object" }, "guest_id": { "format": "uuid", "title": "The guest who signed for a room charge — the reservation's guest", "type": "string", "x-aerandil-references": "hospitality.person" }, "override_reason": { "title": "Override the stay's no-post or credit refusal, and why (room_charge and charge_to_key) — taken under a manager's own session: an F&B manager, a front-office supervisor, the manager on duty, the general manager or the owner, active at the check's house", "type": "string" }, "reservation_id": { "format": "uuid", "title": "The reservation the room-charge folio is a window of (required for room_charge)", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "settled_at": { "format": "date-time", "title": "When the check settled — business time, not record time (defaults to now)", "type": "string" }, "settlement_reference": { "title": "The processor's reference for the tender (the payment's psp_reference)", "type": "string" }, "tender": { "enum": [ "room_charge", "cash", "card", "comp", "external", "charge_to_key" ], "title": "Settlement tender (required unless nothing is due)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.check_payment_on_check", "hospitality.link.check_payment_to_folio", "hospitality.link.folio_has_charge", "hospitality.link.charge_at_outlet", "hospitality.link.charge_has_tax_application", "hospitality.link.check_payment_posted_charge", "hospitality.link.check_settled_to_folio", "hospitality.link.charge_via_credential", "hospitality.link.receipt_for_check", "hospitality.link.package_sale_has_consumption", "hospitality.link.consumption_for_charge", "hospitality.link.charge_attributed_to_package_sale", "hospitality.link.charge_attributed_to_package_component", "hospitality.link.consumption_for_check_payment" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.check_payment", "hospitality.guest_check", "hospitality.charge", "hospitality.tax_application", "hospitality.folio", "hospitality.service_table", "hospitality.check_receipt", "hospitality.package_component_consumption", "hospitality.package_sale" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Settle check (dry-run)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.settle_check/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_settle_check`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_settle_check", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "authorised_by": { "format": "uuid", "title": "Confirms the overriding manager (optional; with override_reason): must be the staff member signed in — the override's authoriser is always the session's own, never one named here", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "credential_token": { "title": "The tapped room key's token (required for charge_to_key)", "type": "string" }, "folio_id": { "format": "uuid", "title": "Folio to receive the room charge (required for room_charge)", "type": "string", "x-aerandil-references": "hospitality.folio" }, "gratuity": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Gratuity — the payment's tip", "type": "object" }, "guest_id": { "format": "uuid", "title": "The guest who signed for a room charge — the reservation's guest", "type": "string", "x-aerandil-references": "hospitality.person" }, "override_reason": { "title": "Override the stay's no-post or credit refusal, and why (room_charge and charge_to_key) — taken under a manager's own session: an F&B manager, a front-office supervisor, the manager on duty, the general manager or the owner, active at the check's house", "type": "string" }, "reservation_id": { "format": "uuid", "title": "The reservation the room-charge folio is a window of (required for room_charge)", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "settled_at": { "format": "date-time", "title": "When the check settled — business time, not record time (defaults to now)", "type": "string" }, "settlement_reference": { "title": "The processor's reference for the tender (the payment's psp_reference)", "type": "string" }, "tender": { "enum": [ "room_charge", "cash", "card", "comp", "external", "charge_to_key" ], "title": "Settlement tender (required unless nothing is due)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Settle check (dry-run)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.settle_check/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_settle_check` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.settle_check:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_settle_check", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "authorised_by": { "format": "uuid", "title": "Confirms the overriding manager (optional; with override_reason): must be the staff member signed in — the override's authoriser is always the session's own, never one named here", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "credential_token": { "title": "The tapped room key's token (required for charge_to_key)", "type": "string" }, "folio_id": { "format": "uuid", "title": "Folio to receive the room charge (required for room_charge)", "type": "string", "x-aerandil-references": "hospitality.folio" }, "gratuity": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Gratuity — the payment's tip", "type": "object" }, "guest_id": { "format": "uuid", "title": "The guest who signed for a room charge — the reservation's guest", "type": "string", "x-aerandil-references": "hospitality.person" }, "override_reason": { "title": "Override the stay's no-post or credit refusal, and why (room_charge and charge_to_key) — taken under a manager's own session: an F&B manager, a front-office supervisor, the manager on duty, the general manager or the owner, active at the check's house", "type": "string" }, "reservation_id": { "format": "uuid", "title": "The reservation the room-charge folio is a window of (required for room_charge)", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "settled_at": { "format": "date-time", "title": "When the check settled — business time, not record time (defaults to now)", "type": "string" }, "settlement_reference": { "title": "The processor's reference for the tender (the payment's psp_reference)", "type": "string" }, "tender": { "enum": [ "room_charge", "cash", "card", "comp", "external", "charge_to_key" ], "title": "Settlement tender (required unless nothing is due)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Settle check (rollup delta)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.settle_commission_without_payment/apply": { "post": { "description": "Close a commission row without sending money. `prepaid` means the guest already paid the agent net, so paying again would pay twice; `offset_to_ar` settles it against what the agent already owes us; `reconciled` is how a channel row ends when the channel's own invoice arrived and matched; `voided` is for a row accrued in error.\n\nEffects: modify hospitality.commission_detail.", "operationId": "apply_hospitality_action_settle_commission_without_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "outcome": { "enum": [ "prepaid", "offset_to_ar", "reconciled", "voided" ], "title": "How the row settled", "type": "string" }, "reason": { "title": "Why it settled this way", "type": "string" } }, "required": [ "outcome", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.commission_detail" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.commission_detail" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.settle_commission_without_payment:apply" ] } ], "summary": "Settle commission without payment", "tags": [ "commission" ] } }, "/v1/actions/hospitality.action.settle_commission_without_payment/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_settle_commission_without_payment` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.settle_commission_without_payment:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_settle_commission_without_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "outcome": { "enum": [ "prepaid", "offset_to_ar", "reconciled", "voided" ], "title": "How the row settled", "type": "string" }, "reason": { "title": "Why it settled this way", "type": "string" } }, "required": [ "outcome", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.commission_detail" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.commission_detail" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Settle commission without payment (dry-run)", "tags": [ "commission" ] } }, "/v1/actions/hospitality.action.settle_commission_without_payment/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_settle_commission_without_payment`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_settle_commission_without_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "outcome": { "enum": [ "prepaid", "offset_to_ar", "reconciled", "voided" ], "title": "How the row settled", "type": "string" }, "reason": { "title": "Why it settled this way", "type": "string" } }, "required": [ "outcome", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.commission_detail" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Settle commission without payment (dry-run)", "tags": [ "commission" ] } }, "/v1/actions/hospitality.action.settle_commission_without_payment/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_settle_commission_without_payment` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.settle_commission_without_payment:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_settle_commission_without_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "outcome": { "enum": [ "prepaid", "offset_to_ar", "reconciled", "voided" ], "title": "How the row settled", "type": "string" }, "reason": { "title": "Why it settled this way", "type": "string" } }, "required": [ "outcome", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.commission_detail" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Settle commission without payment (rollup delta)", "tags": [ "commission" ] } }, "/v1/actions/hospitality.action.settle_folio_to_ar/apply": { "post": { "description": "Move an outstanding-balance folio onto a company A/R folio. Sets `ar_transferred_at` and `due_at`. The aging cycle maintains `ar_aging_bucket` thereafter.\n\nEffects: modify hospitality.folio; link hospitality.link.folio_settled_by_company_ar.", "operationId": "apply_hospitality_action_settle_folio_to_ar", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "due_at": { "format": "date-time", "title": "Due at", "type": "string" }, "target_company_ar_folio_id": { "format": "uuid", "title": "Target company A/R folio", "type": "string", "x-aerandil-references": "hospitality.folio" } }, "required": [ "target_company_ar_folio_id", "due_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_settled_by_company_ar" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.settle_folio_to_ar:apply" ] } ], "summary": "Settle folio to A/R", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.settle_folio_to_ar/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_settle_folio_to_ar` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.settle_folio_to_ar:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_settle_folio_to_ar", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "due_at": { "format": "date-time", "title": "Due at", "type": "string" }, "target_company_ar_folio_id": { "format": "uuid", "title": "Target company A/R folio", "type": "string", "x-aerandil-references": "hospitality.folio" } }, "required": [ "target_company_ar_folio_id", "due_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_settled_by_company_ar" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Settle folio to A/R (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.settle_folio_to_ar/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_settle_folio_to_ar`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_settle_folio_to_ar", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "due_at": { "format": "date-time", "title": "Due at", "type": "string" }, "target_company_ar_folio_id": { "format": "uuid", "title": "Target company A/R folio", "type": "string", "x-aerandil-references": "hospitality.folio" } }, "required": [ "target_company_ar_folio_id", "due_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Settle folio to A/R (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.settle_folio_to_ar/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_settle_folio_to_ar` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.settle_folio_to_ar:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_settle_folio_to_ar", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "due_at": { "format": "date-time", "title": "Due at", "type": "string" }, "target_company_ar_folio_id": { "format": "uuid", "title": "Target company A/R folio", "type": "string", "x-aerandil-references": "hospitality.folio" } }, "required": [ "target_company_ar_folio_id", "due_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Settle folio to A/R (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.sign_registration_card/apply": { "post": { "description": "Record the registration card the guest signed at the desk for this stay: the house's terms exactly as shown (`terms_text`, with a `terms_version` label or hash), the name signed under, and the signature's strokes as SVG path data (`signature_svg_paths`: `M` and `L` commands with numbers only, at most 64 KB — nothing but the strokes is stored). Linked to the stay and to its reservation, signed at the kernel's clock, captured by the calling principal. One current card per stay: signing again replaces the current card, which is kept as `superseded`. A chargeback's evidence packet attaches the current card as `customer_signature`. Refuses a stay that is not checked in or checked out, empty or malformed strokes, and strokes over the limit. Emits `registration_card.signed` (never the strokes or the name).\n\nEffects: create hospitality.registration_card; modify hospitality.registration_card; link hospitality.link.registration_card_for_stay; link hospitality.link.registration_card_for_reservation.", "operationId": "apply_hospitality_action_sign_registration_card", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "device_label": { "title": "The desk device the guest signed on", "type": "string" }, "signature_height": { "title": "The pad's height in the strokes' units", "type": "integer" }, "signature_svg_paths": { "title": "The strokes as SVG path data (M and L commands, at most 64 KB)", "type": "string" }, "signature_width": { "title": "The pad's width in the strokes' units", "type": "integer" }, "signer_name": { "title": "The name the guest signed under", "type": "string" }, "terms_text": { "title": "The terms the guest was shown, verbatim", "type": "string" }, "terms_version": { "title": "Which version of the house's terms was shown (a label or a hash)", "type": "string" } }, "required": [ "signer_name", "terms_version", "terms_text", "signature_svg_paths" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.registration_card_for_stay", "hospitality.link.registration_card_for_reservation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.registration_card" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.sign_registration_card:apply" ] } ], "summary": "Sign registration card", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.sign_registration_card/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_sign_registration_card` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.sign_registration_card:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_sign_registration_card", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "device_label": { "title": "The desk device the guest signed on", "type": "string" }, "signature_height": { "title": "The pad's height in the strokes' units", "type": "integer" }, "signature_svg_paths": { "title": "The strokes as SVG path data (M and L commands, at most 64 KB)", "type": "string" }, "signature_width": { "title": "The pad's width in the strokes' units", "type": "integer" }, "signer_name": { "title": "The name the guest signed under", "type": "string" }, "terms_text": { "title": "The terms the guest was shown, verbatim", "type": "string" }, "terms_version": { "title": "Which version of the house's terms was shown (a label or a hash)", "type": "string" } }, "required": [ "signer_name", "terms_version", "terms_text", "signature_svg_paths" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.registration_card_for_stay", "hospitality.link.registration_card_for_reservation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.registration_card" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Sign registration card (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.sign_registration_card/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_sign_registration_card`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_sign_registration_card", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "device_label": { "title": "The desk device the guest signed on", "type": "string" }, "signature_height": { "title": "The pad's height in the strokes' units", "type": "integer" }, "signature_svg_paths": { "title": "The strokes as SVG path data (M and L commands, at most 64 KB)", "type": "string" }, "signature_width": { "title": "The pad's width in the strokes' units", "type": "integer" }, "signer_name": { "title": "The name the guest signed under", "type": "string" }, "terms_text": { "title": "The terms the guest was shown, verbatim", "type": "string" }, "terms_version": { "title": "Which version of the house's terms was shown (a label or a hash)", "type": "string" } }, "required": [ "signer_name", "terms_version", "terms_text", "signature_svg_paths" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Sign registration card (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.sign_registration_card/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_sign_registration_card` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.sign_registration_card:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_sign_registration_card", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "device_label": { "title": "The desk device the guest signed on", "type": "string" }, "signature_height": { "title": "The pad's height in the strokes' units", "type": "integer" }, "signature_svg_paths": { "title": "The strokes as SVG path data (M and L commands, at most 64 KB)", "type": "string" }, "signature_width": { "title": "The pad's width in the strokes' units", "type": "integer" }, "signer_name": { "title": "The name the guest signed under", "type": "string" }, "terms_text": { "title": "The terms the guest was shown, verbatim", "type": "string" }, "terms_version": { "title": "Which version of the house's terms was shown (a label or a hash)", "type": "string" } }, "required": [ "signer_name", "terms_version", "terms_text", "signature_svg_paths" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Sign registration card (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.skip_housekeeping_task/apply": { "post": { "description": "Record work deliberately not done, with the reason — the guest declined service, the room is being retired for the day. Terminal: a skipped task never restarts (mint a fresh one if the work comes back).\n\nEffects: modify hospitality.housekeeping_task.", "operationId": "apply_hospitality_action_skip_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "skip_reason": { "title": "Why the work is not being done", "type": "string" } }, "required": [ "skip_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.skip_housekeeping_task:apply" ] } ], "summary": "Skip housekeeping task", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.skip_housekeeping_task/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_skip_housekeeping_task` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.skip_housekeeping_task:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_skip_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "skip_reason": { "title": "Why the work is not being done", "type": "string" } }, "required": [ "skip_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Skip housekeeping task (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.skip_housekeeping_task/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_skip_housekeeping_task`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_skip_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "skip_reason": { "title": "Why the work is not being done", "type": "string" } }, "required": [ "skip_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Skip housekeeping task (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.skip_housekeeping_task/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_skip_housekeeping_task` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.skip_housekeeping_task:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_skip_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "skip_reason": { "title": "Why the work is not being done", "type": "string" } }, "required": [ "skip_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Skip housekeeping task (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.split_person_merge/apply": { "post": { "description": "Reversible unmerge of the targeted subordinate person: close the live `person_merged_into` link (`effective_to` stamp — the row stays as history) and restore `resolution_status = active`. Re-merging afterwards is a fresh `propose_person_match` → confirm; confirmed candidates are terminal audit rows and are never re-opened. Emits `person.merge_split`.\n\nEffects: unlink hospitality.link.person_merged_into; modify hospitality.person.", "operationId": "apply_hospitality_action_split_person_merge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.person_merged_into" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.person" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.split_person_merge:apply" ] } ], "summary": "Split person merge", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.split_person_merge/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_split_person_merge` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.split_person_merge:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_split_person_merge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.person_merged_into" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.person" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Split person merge (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.split_person_merge/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_split_person_merge`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_split_person_merge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Split person merge (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.split_person_merge/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_split_person_merge` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.split_person_merge:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_split_person_merge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Split person merge (rollup delta)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.start_channel_publication/apply": { "post": { "description": "Open one audited ARI push against an `active` conduit — creates a `channel_publication_run` in `running` and links it. `delta` is the steady state and the only trigger permitted in normal operation: SiteMinder enforces delta-only publication and names repeated full flushes inside 24 hours as grounds for immediate interface suspension. So `full`, `recovery` and `manual` are refused when `channel_connection.last_full_publication_at` is inside the last 24 hours, and a successful one stamps it. Emits `channel_publication.started`.\n\nEffects: create hospitality.channel_publication_run; modify hospitality.channel_connection; link hospitality.link.publication_run_for_connection.", "operationId": "apply_hospitality_action_start_channel_publication", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "trigger": { "enum": [ "delta", "full", "recovery", "manual" ], "title": "What initiated this run", "type": "string" }, "window_end": { "format": "date", "title": "Last business date to cover (defaults to the conduit's horizon)", "type": "string" }, "window_start": { "format": "date", "title": "First business date to cover (delta runs derive it from the outbox)", "type": "string" } }, "required": [ "trigger" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.publication_run_for_connection" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.channel_publication_run", "hospitality.channel_connection" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.start_channel_publication:apply" ] } ], "summary": "Start channel publication", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.start_channel_publication/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_start_channel_publication` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.start_channel_publication:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_start_channel_publication", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "trigger": { "enum": [ "delta", "full", "recovery", "manual" ], "title": "What initiated this run", "type": "string" }, "window_end": { "format": "date", "title": "Last business date to cover (defaults to the conduit's horizon)", "type": "string" }, "window_start": { "format": "date", "title": "First business date to cover (delta runs derive it from the outbox)", "type": "string" } }, "required": [ "trigger" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.publication_run_for_connection" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.channel_publication_run", "hospitality.channel_connection" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Start channel publication (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.start_channel_publication/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_start_channel_publication`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_start_channel_publication", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "trigger": { "enum": [ "delta", "full", "recovery", "manual" ], "title": "What initiated this run", "type": "string" }, "window_end": { "format": "date", "title": "Last business date to cover (defaults to the conduit's horizon)", "type": "string" }, "window_start": { "format": "date", "title": "First business date to cover (delta runs derive it from the outbox)", "type": "string" } }, "required": [ "trigger" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Start channel publication (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.start_channel_publication/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_start_channel_publication` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.start_channel_publication:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_start_channel_publication", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "trigger": { "enum": [ "delta", "full", "recovery", "manual" ], "title": "What initiated this run", "type": "string" }, "window_end": { "format": "date", "title": "Last business date to cover (defaults to the conduit's horizon)", "type": "string" }, "window_start": { "format": "date", "title": "First business date to cover (delta runs derive it from the outbox)", "type": "string" } }, "required": [ "trigger" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Start channel publication (rollup delta)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.start_connector_sync/apply": { "post": { "description": "Open one audited sync run against an `active` connector — creates a `connector_sync_run` in `running` and links it. Called by the ingest worker on schedule, or manually from the Explorer (trigger = manual / backfill). A run brackets one stream, so `mapping_ref` pins which mapping version it loaded under; it defaults to the connector's only mapping when it carries exactly one, and must be given explicitly on a multi-stream connector (there is no principled default among several). Emits `connector.sync_started`.\n\nEffects: create hospitality.connector_sync_run; link hospitality.link.sync_run_for_connector.", "operationId": "apply_hospitality_action_start_connector_sync", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "mapping_ref": { "title": "Mapping definition version to load under (defaults to the connector's)", "type": "string" }, "streams": { "items": { "type": "string" }, "title": "Source streams to pull (vendor vocabulary; empty = connector default)", "type": "array" }, "trigger": { "enum": [ "scheduled", "manual", "backfill" ], "title": "What initiated this run", "type": "string" } }, "required": [ "trigger" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.sync_run_for_connector" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.connector_sync_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.start_connector_sync:apply" ] } ], "summary": "Start connector sync", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.start_connector_sync/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_start_connector_sync` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.start_connector_sync:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_start_connector_sync", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "mapping_ref": { "title": "Mapping definition version to load under (defaults to the connector's)", "type": "string" }, "streams": { "items": { "type": "string" }, "title": "Source streams to pull (vendor vocabulary; empty = connector default)", "type": "array" }, "trigger": { "enum": [ "scheduled", "manual", "backfill" ], "title": "What initiated this run", "type": "string" } }, "required": [ "trigger" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.sync_run_for_connector" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.connector_sync_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Start connector sync (dry-run)", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.start_connector_sync/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_start_connector_sync`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_start_connector_sync", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "mapping_ref": { "title": "Mapping definition version to load under (defaults to the connector's)", "type": "string" }, "streams": { "items": { "type": "string" }, "title": "Source streams to pull (vendor vocabulary; empty = connector default)", "type": "array" }, "trigger": { "enum": [ "scheduled", "manual", "backfill" ], "title": "What initiated this run", "type": "string" } }, "required": [ "trigger" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Start connector sync (dry-run)", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.start_connector_sync/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_start_connector_sync` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.start_connector_sync:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_start_connector_sync", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "mapping_ref": { "title": "Mapping definition version to load under (defaults to the connector's)", "type": "string" }, "streams": { "items": { "type": "string" }, "title": "Source streams to pull (vendor vocabulary; empty = connector default)", "type": "array" }, "trigger": { "enum": [ "scheduled", "manual", "backfill" ], "title": "What initiated this run", "type": "string" } }, "required": [ "trigger" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Start connector sync (rollup delta)", "tags": [ "connectors" ] } }, "/v1/actions/hospitality.action.start_federated_run/apply": { "post": { "description": "Start a run for an approved definition and cohort. Freezes the definition version and cohort snapshot, resolves eligible active participants, validates thresholds before collection, reserves privacy budget, and creates the run with status `collecting`. Idempotent on `run_key`. Validators (commit 5): `run_definition_must_be_approved`, `run_cohort_must_be_approved`, `run_input_window_end_le_now_unless_forecast`, `run_minimum_participants_before_collection`, `run_privacy_budget_reservation_must_succeed`.\n\nEffects: create hospitality.federated_run; create hospitality.privacy_budget_event; modify hospitality.privacy_budget_account; link hospitality.link.federated_run_uses_definition; link hospitality.link.federated_run_uses_cohort; link hospitality.link.federated_run_started_by_workflow; link hospitality.link.federated_run_reserved_from_account.", "operationId": "apply_hospitality_action_start_federated_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "aggregation_protocol": { "enum": [ "plain_aggregate_reviewed", "secure_aggregation", "clean_room_dp", "external_protocol" ], "title": "Aggregation protocol", "type": "string" }, "clean_room_job_ref": { "title": "Required for third-party clean room", "type": "string" }, "cohort_id": { "title": "Approved cohort id", "type": "string" }, "deadline_at": { "format": "date-time", "title": "Contribution deadline", "type": "string" }, "initiating_workflow_run_id": { "title": "Set when a proposal 0020 workflow started this run", "type": "string" }, "input_window_end": { "format": "date-time", "title": "Input window end", "type": "string" }, "input_window_start": { "format": "date-time", "title": "Input window start", "type": "string" }, "privacy_budget_account_id": { "title": "Privacy budget account to reserve from. Required when the definition's mechanism_family is a DP variant; the handler dispatches reserve_privacy_budget against this account keyed on the run's correlation_id (idempotent, atomic). Resolves to the (program, composition_group) account in practice; explicit reference avoids the multi-account ambiguity at the action boundary.", "type": "string" }, "run_key": { "title": "Optional caller-supplied idempotency key; otherwise derived", "type": "string" }, "secure_aggregation_session_ref": { "title": "Required for secure aggregation", "type": "string" }, "trigger_kind": { "enum": [ "scheduled", "manual", "workflow", "agent_request", "backfill" ], "title": "Scheduled / manual / workflow / agent / backfill", "type": "string" } }, "required": [ "cohort_id", "input_window_start", "input_window_end", "trigger_kind", "aggregation_protocol" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_analysis_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.federated_run_uses_definition", "hospitality.link.federated_run_uses_cohort", "hospitality.link.federated_run_started_by_workflow", "hospitality.link.federated_run_reserved_from_account" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.federated_run", "hospitality.privacy_budget_event", "hospitality.privacy_budget_account" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.start_federated_run:apply" ] } ], "summary": "Start federated run", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.start_federated_run/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_start_federated_run` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.start_federated_run:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_start_federated_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "aggregation_protocol": { "enum": [ "plain_aggregate_reviewed", "secure_aggregation", "clean_room_dp", "external_protocol" ], "title": "Aggregation protocol", "type": "string" }, "clean_room_job_ref": { "title": "Required for third-party clean room", "type": "string" }, "cohort_id": { "title": "Approved cohort id", "type": "string" }, "deadline_at": { "format": "date-time", "title": "Contribution deadline", "type": "string" }, "initiating_workflow_run_id": { "title": "Set when a proposal 0020 workflow started this run", "type": "string" }, "input_window_end": { "format": "date-time", "title": "Input window end", "type": "string" }, "input_window_start": { "format": "date-time", "title": "Input window start", "type": "string" }, "privacy_budget_account_id": { "title": "Privacy budget account to reserve from. Required when the definition's mechanism_family is a DP variant; the handler dispatches reserve_privacy_budget against this account keyed on the run's correlation_id (idempotent, atomic). Resolves to the (program, composition_group) account in practice; explicit reference avoids the multi-account ambiguity at the action boundary.", "type": "string" }, "run_key": { "title": "Optional caller-supplied idempotency key; otherwise derived", "type": "string" }, "secure_aggregation_session_ref": { "title": "Required for secure aggregation", "type": "string" }, "trigger_kind": { "enum": [ "scheduled", "manual", "workflow", "agent_request", "backfill" ], "title": "Scheduled / manual / workflow / agent / backfill", "type": "string" } }, "required": [ "cohort_id", "input_window_start", "input_window_end", "trigger_kind", "aggregation_protocol" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_analysis_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.federated_run_uses_definition", "hospitality.link.federated_run_uses_cohort", "hospitality.link.federated_run_started_by_workflow", "hospitality.link.federated_run_reserved_from_account" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.federated_run", "hospitality.privacy_budget_event", "hospitality.privacy_budget_account" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Start federated run (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.start_federated_run/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_start_federated_run`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_start_federated_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "aggregation_protocol": { "enum": [ "plain_aggregate_reviewed", "secure_aggregation", "clean_room_dp", "external_protocol" ], "title": "Aggregation protocol", "type": "string" }, "clean_room_job_ref": { "title": "Required for third-party clean room", "type": "string" }, "cohort_id": { "title": "Approved cohort id", "type": "string" }, "deadline_at": { "format": "date-time", "title": "Contribution deadline", "type": "string" }, "initiating_workflow_run_id": { "title": "Set when a proposal 0020 workflow started this run", "type": "string" }, "input_window_end": { "format": "date-time", "title": "Input window end", "type": "string" }, "input_window_start": { "format": "date-time", "title": "Input window start", "type": "string" }, "privacy_budget_account_id": { "title": "Privacy budget account to reserve from. Required when the definition's mechanism_family is a DP variant; the handler dispatches reserve_privacy_budget against this account keyed on the run's correlation_id (idempotent, atomic). Resolves to the (program, composition_group) account in practice; explicit reference avoids the multi-account ambiguity at the action boundary.", "type": "string" }, "run_key": { "title": "Optional caller-supplied idempotency key; otherwise derived", "type": "string" }, "secure_aggregation_session_ref": { "title": "Required for secure aggregation", "type": "string" }, "trigger_kind": { "enum": [ "scheduled", "manual", "workflow", "agent_request", "backfill" ], "title": "Scheduled / manual / workflow / agent / backfill", "type": "string" } }, "required": [ "cohort_id", "input_window_start", "input_window_end", "trigger_kind", "aggregation_protocol" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_analysis_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Start federated run (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.start_federated_run/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_start_federated_run` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.start_federated_run:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_start_federated_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "aggregation_protocol": { "enum": [ "plain_aggregate_reviewed", "secure_aggregation", "clean_room_dp", "external_protocol" ], "title": "Aggregation protocol", "type": "string" }, "clean_room_job_ref": { "title": "Required for third-party clean room", "type": "string" }, "cohort_id": { "title": "Approved cohort id", "type": "string" }, "deadline_at": { "format": "date-time", "title": "Contribution deadline", "type": "string" }, "initiating_workflow_run_id": { "title": "Set when a proposal 0020 workflow started this run", "type": "string" }, "input_window_end": { "format": "date-time", "title": "Input window end", "type": "string" }, "input_window_start": { "format": "date-time", "title": "Input window start", "type": "string" }, "privacy_budget_account_id": { "title": "Privacy budget account to reserve from. Required when the definition's mechanism_family is a DP variant; the handler dispatches reserve_privacy_budget against this account keyed on the run's correlation_id (idempotent, atomic). Resolves to the (program, composition_group) account in practice; explicit reference avoids the multi-account ambiguity at the action boundary.", "type": "string" }, "run_key": { "title": "Optional caller-supplied idempotency key; otherwise derived", "type": "string" }, "secure_aggregation_session_ref": { "title": "Required for secure aggregation", "type": "string" }, "trigger_kind": { "enum": [ "scheduled", "manual", "workflow", "agent_request", "backfill" ], "title": "Scheduled / manual / workflow / agent / backfill", "type": "string" } }, "required": [ "cohort_id", "input_window_start", "input_window_end", "trigger_kind", "aggregation_protocol" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_analysis_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Start federated run (rollup delta)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.start_housekeeping_task/apply": { "post": { "description": "The attendant is in the room: pending / blocked → in_progress, stamping started_at (the cleaning-duration feed) and clearing any block reason — starting a blocked task is the retry after a do-not-disturb. An unassigned task started by a staff-member principal (a handset session) is assigned to that attendant in the same write — picking up the next room needs no supervisor round trip; an already-assigned task is left as assigned (reassignment stays a supervisor verb). A task assigned to a worker group (2026-10-14) is taken by the member who starts it — the group edge re-points to them — and a staff-member session outside the group is refused (403); a caller that is not a staff member starts it and leaves it the group's. A start is the holder's (2026-10-17): an attendant, runner or engineer who does not hold a task a colleague holds is refused (403) — they Take it first — while the housekeeping supervisor and the desk start it on the holder's behalf and the assignment stands. `expected_holder_id` names the holder the caller saw (a start queued on a handset): refused (422) when someone else, a group or nobody holds the task by the time it lands.\n\nEffects: modify hospitality.housekeeping_task; link hospitality.link.housekeeping_task_assigned_to; unlink hospitality.link.housekeeping_task_assigned_to_group.", "operationId": "apply_hospitality_action_start_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "expected_holder_id": { "format": "uuid", "title": "Who the caller saw holding it — refused when that has changed", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "started_at": { "format": "date-time", "title": "When the attendant entered (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.housekeeping_task_assigned_to", "hospitality.link.housekeeping_task_assigned_to_group" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.start_housekeeping_task:apply" ] } ], "summary": "Start housekeeping task", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.start_housekeeping_task/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_start_housekeeping_task` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.start_housekeeping_task:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_start_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "expected_holder_id": { "format": "uuid", "title": "Who the caller saw holding it — refused when that has changed", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "started_at": { "format": "date-time", "title": "When the attendant entered (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.housekeeping_task_assigned_to", "hospitality.link.housekeeping_task_assigned_to_group" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.housekeeping_task" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Start housekeeping task (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.start_housekeeping_task/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_start_housekeeping_task`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_start_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "expected_holder_id": { "format": "uuid", "title": "Who the caller saw holding it — refused when that has changed", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "started_at": { "format": "date-time", "title": "When the attendant entered (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Start housekeeping task (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.start_housekeeping_task/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_start_housekeeping_task` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.start_housekeeping_task:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_start_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "expected_holder_id": { "format": "uuid", "title": "Who the caller saw holding it — refused when that has changed", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "started_at": { "format": "date-time", "title": "When the attendant entered (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Start housekeeping task (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.start_inspection_round/apply": { "post": { "description": "Start a round from an active template — by hand, or the automation sweep's effect when the template falls due. The round carries the template's name, family, the due date it answers (`due_on`, the template's `next_due_on`) and its checkpoints as they stand now; it starts `open`, `started_by` the principal (and linked to the staff member behind a handset session), and the template's `open_round_id` names it. One open round per template: while one is open, the same caller starting again — or the same `round_id` — is a replay that writes nothing, and anyone else is refused, naming the open round. `round_id` is the round's id when the caller mints it (a v4 or v7 UUID — a handset starting a walk with no signal records its checkpoints against it before the start lands); the same id on another template is refused as a duplicate. Refuses a retired template. `template_revision` (2026-10-17) is the template's `revision` the caller saw — a handset queueing a start names the walk it shows: when the template has been revised since, the start is refused (409 `version_conflict`, `expected_version` the stated revision and `current_version` the template's) and nothing opens, so readings queued against the old positions never land on moved checkpoints; a start already landed under the same `round_id` is a replay whatever it names. The round records the revision it copied (`template_revision`). Emits `inspection_round.started`. A person's start under a minted `round_id` takes over a round the automation sweep opened (`started_by` an automation) that nothing has been recorded on yet (2026-10-17) — the walk queued on a handset that was offline when the template fell due: the sweep's round is cancelled (`cancel_reason` naming the walk that took it; `inspection_round.cancelled` with `taken_over_by`), the caller's round opens for the same due date and stands (`inspection_round.started` with `took_over`; the response lists both and an `inspection-round-taken-over` warning names them). A sweep's round with a checkpoint recorded is someone's walk and is not taken: the start is refused, naming it, as any other open round.\n\nEffects: create hospitality.inspection_round; modify hospitality.round_template; link hospitality.link.inspection_round_from_template; link hospitality.link.inspection_round_started_by; modify hospitality.inspection_round.", "operationId": "apply_hospitality_action_start_inspection_round", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "round_id": { "title": "The round's id, minted by the caller (a v4 or v7 UUID)", "type": "string" }, "started_at": { "format": "date-time", "title": "When the walk began (defaults to now; the handset's own time when it queued)", "type": "string" }, "template_revision": { "title": "The template's revision the caller saw — refused (409) when it has moved on", "type": "integer" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.round_template" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.inspection_round_from_template", "hospitality.link.inspection_round_started_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.inspection_round", "hospitality.round_template" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.start_inspection_round:apply" ] } ], "summary": "Start inspection round", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.start_inspection_round/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_start_inspection_round` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.start_inspection_round:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_start_inspection_round", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "round_id": { "title": "The round's id, minted by the caller (a v4 or v7 UUID)", "type": "string" }, "started_at": { "format": "date-time", "title": "When the walk began (defaults to now; the handset's own time when it queued)", "type": "string" }, "template_revision": { "title": "The template's revision the caller saw — refused (409) when it has moved on", "type": "integer" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.round_template" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.inspection_round_from_template", "hospitality.link.inspection_round_started_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.inspection_round", "hospitality.round_template" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Start inspection round (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.start_inspection_round/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_start_inspection_round`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_start_inspection_round", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "round_id": { "title": "The round's id, minted by the caller (a v4 or v7 UUID)", "type": "string" }, "started_at": { "format": "date-time", "title": "When the walk began (defaults to now; the handset's own time when it queued)", "type": "string" }, "template_revision": { "title": "The template's revision the caller saw — refused (409) when it has moved on", "type": "integer" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.round_template" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Start inspection round (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.start_inspection_round/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_start_inspection_round` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.start_inspection_round:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_start_inspection_round", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "round_id": { "title": "The round's id, minted by the caller (a v4 or v7 UUID)", "type": "string" }, "started_at": { "format": "date-time", "title": "When the walk began (defaults to now; the handset's own time when it queued)", "type": "string" }, "template_revision": { "title": "The template's revision the caller saw — refused (409) when it has moved on", "type": "integer" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.round_template" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Start inspection round (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.start_residency/apply": { "post": { "description": "Start a residency at the target venue — chef pop-up, partner-brand activation, talent residency. Creates a temporal `venue_residency` link from the venue to the partner company with an `effective_from` date. End the residency via `end_residency` (sets `effective_to`).\n\nEffects: link hospitality.link.venue_residency.", "operationId": "apply_hospitality_action_start_residency", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "company_id": { "format": "uuid", "title": "Partner company (chef LLC / partner brand operator)", "type": "string", "x-aerandil-references": "hospitality.company" }, "effective_from": { "format": "date-time", "title": "Residency start", "type": "string" }, "planned_end": { "format": "date-time", "title": "Planned end (optional — set on the link as effective_to if known)", "type": "string" } }, "required": [ "company_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.venue_residency" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.start_residency:apply" ] } ], "summary": "Start residency", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.start_residency/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_start_residency` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.start_residency:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_start_residency", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "company_id": { "format": "uuid", "title": "Partner company (chef LLC / partner brand operator)", "type": "string", "x-aerandil-references": "hospitality.company" }, "effective_from": { "format": "date-time", "title": "Residency start", "type": "string" }, "planned_end": { "format": "date-time", "title": "Planned end (optional — set on the link as effective_to if known)", "type": "string" } }, "required": [ "company_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.venue_residency" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Start residency (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.start_residency/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_start_residency`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_start_residency", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "company_id": { "format": "uuid", "title": "Partner company (chef LLC / partner brand operator)", "type": "string", "x-aerandil-references": "hospitality.company" }, "effective_from": { "format": "date-time", "title": "Residency start", "type": "string" }, "planned_end": { "format": "date-time", "title": "Planned end (optional — set on the link as effective_to if known)", "type": "string" } }, "required": [ "company_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Start residency (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.start_residency/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_start_residency` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.start_residency:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_start_residency", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "company_id": { "format": "uuid", "title": "Partner company (chef LLC / partner brand operator)", "type": "string", "x-aerandil-references": "hospitality.company" }, "effective_from": { "format": "date-time", "title": "Residency start", "type": "string" }, "planned_end": { "format": "date-time", "title": "Planned end (optional — set on the link as effective_to if known)", "type": "string" } }, "required": [ "company_id", "effective_from" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Start residency (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.start_work_order/apply": { "post": { "description": "The engineer is on the job: open / scheduled / blocked / postponed → in_progress, stamping started_at and clearing any block reason or postponement (starting a blocked order is the retry after parts arrived; starting a postponed one is its resume). An order assigned to a worker group (2026-10-14) is taken by the member who starts it — the group edge re-points to them — and a staff-member session outside the group is refused (403); a caller that is not a staff member starts it and leaves it the group's.\n\nEffects: modify hospitality.work_order; link hospitality.link.work_order_assigned_to; unlink hospitality.link.work_order_assigned_to_group.", "operationId": "apply_hospitality_action_start_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "started_at": { "format": "date-time", "title": "When work began (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.work_order_assigned_to", "hospitality.link.work_order_assigned_to_group" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.work_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.start_work_order:apply" ] } ], "summary": "Start work order", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.start_work_order/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_start_work_order` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.start_work_order:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_start_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "started_at": { "format": "date-time", "title": "When work began (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.work_order_assigned_to", "hospitality.link.work_order_assigned_to_group" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.work_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Start work order (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.start_work_order/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_start_work_order`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_start_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "started_at": { "format": "date-time", "title": "When work began (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Start work order (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.start_work_order/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_start_work_order` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.start_work_order:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_start_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "started_at": { "format": "date-time", "title": "When work began (defaults to now)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Start work order (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.start_workflow_run/apply": { "post": { "description": "Start a durable execution pinned to an active definition version. Inserts a `workflow_run` (status `pending`), copies `definition_hash`, freezes `input_snapshot` and `target_refs_snapshot`, inserts initial `workflow_step_run` rows with non-root steps in `planned` and root steps (`depends_on = []`) synchronously promoted to `ready` before commit (AWS Step Functions `StartAt` precedent), creates concrete `workflow_run_targets_*` links per supported target type, and emits §9.1 events `workflow_run.started`, `workflow_step.planned`, `workflow_step.ready`. Does not start a runner — advancement requires the future executor actions.\n\nEffects: create hospitality.workflow_run; create hospitality.workflow_step_run; link hospitality.link.workflow_run_for_definition; link hospitality.link.workflow_step_run_for_workflow_run; link hospitality.link.workflow_run_started_by_agent_installation; modify hospitality.workflow_run; link hospitality.link.workflow_run_targets_reservation; link hospitality.link.workflow_run_targets_payment; link hospitality.link.workflow_run_targets_folio; link hospitality.link.workflow_run_targets_charge; link hospitality.link.workflow_run_targets_person; link hospitality.link.workflow_run_targets_staff_member; link hospitality.link.workflow_run_targets_service_recovery_event; link hospitality.link.workflow_run_targets_fraud_risk_assessment; link hospitality.link.workflow_run_targets_message_triage; link hospitality.link.workflow_run_targets_rate_recommendation; link hospitality.link.workflow_run_targets_restriction_recommendation; link hospitality.link.workflow_run_targets_room; link hospitality.link.workflow_run_targets_membership.", "operationId": "apply_hospitality_action_start_workflow_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "expires_at": { "format": "date-time", "title": "Run timeout", "type": "string" }, "initiating_agent_installation_id": { "title": "Set when an installed agent initiated the run", "type": "string" }, "input": { "title": "Frozen, redacted start input" }, "run_key": { "title": "Host-supplied business / dedupe key", "type": "string" }, "target_refs": { "title": "Optional `[{object_type, object_id}, ...]` for graph wiring" }, "trigger_kind": { "enum": [ "manual", "event", "schedule", "webhook", "agent_requested", "api" ], "title": "Defaults from the definition", "type": "string" } }, "required": [ "run_key", "input" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.workflow_run_for_definition", "hospitality.link.workflow_step_run_for_workflow_run", "hospitality.link.workflow_run_started_by_agent_installation", "hospitality.link.workflow_run_targets_reservation", "hospitality.link.workflow_run_targets_payment", "hospitality.link.workflow_run_targets_folio", "hospitality.link.workflow_run_targets_charge", "hospitality.link.workflow_run_targets_person", "hospitality.link.workflow_run_targets_staff_member", "hospitality.link.workflow_run_targets_service_recovery_event", "hospitality.link.workflow_run_targets_fraud_risk_assessment", "hospitality.link.workflow_run_targets_message_triage", "hospitality.link.workflow_run_targets_rate_recommendation", "hospitality.link.workflow_run_targets_restriction_recommendation", "hospitality.link.workflow_run_targets_room", "hospitality.link.workflow_run_targets_membership" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.workflow_run", "hospitality.workflow_step_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.start_workflow_run:apply" ] } ], "summary": "Start workflow run", "tags": [ "workflows" ] } }, "/v1/actions/hospitality.action.start_workflow_run/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_start_workflow_run` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.start_workflow_run:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_start_workflow_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "expires_at": { "format": "date-time", "title": "Run timeout", "type": "string" }, "initiating_agent_installation_id": { "title": "Set when an installed agent initiated the run", "type": "string" }, "input": { "title": "Frozen, redacted start input" }, "run_key": { "title": "Host-supplied business / dedupe key", "type": "string" }, "target_refs": { "title": "Optional `[{object_type, object_id}, ...]` for graph wiring" }, "trigger_kind": { "enum": [ "manual", "event", "schedule", "webhook", "agent_requested", "api" ], "title": "Defaults from the definition", "type": "string" } }, "required": [ "run_key", "input" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.workflow_run_for_definition", "hospitality.link.workflow_step_run_for_workflow_run", "hospitality.link.workflow_run_started_by_agent_installation", "hospitality.link.workflow_run_targets_reservation", "hospitality.link.workflow_run_targets_payment", "hospitality.link.workflow_run_targets_folio", "hospitality.link.workflow_run_targets_charge", "hospitality.link.workflow_run_targets_person", "hospitality.link.workflow_run_targets_staff_member", "hospitality.link.workflow_run_targets_service_recovery_event", "hospitality.link.workflow_run_targets_fraud_risk_assessment", "hospitality.link.workflow_run_targets_message_triage", "hospitality.link.workflow_run_targets_rate_recommendation", "hospitality.link.workflow_run_targets_restriction_recommendation", "hospitality.link.workflow_run_targets_room", "hospitality.link.workflow_run_targets_membership" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.workflow_run", "hospitality.workflow_step_run" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Start workflow run (dry-run)", "tags": [ "workflows" ] } }, "/v1/actions/hospitality.action.start_workflow_run/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_start_workflow_run`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_start_workflow_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "expires_at": { "format": "date-time", "title": "Run timeout", "type": "string" }, "initiating_agent_installation_id": { "title": "Set when an installed agent initiated the run", "type": "string" }, "input": { "title": "Frozen, redacted start input" }, "run_key": { "title": "Host-supplied business / dedupe key", "type": "string" }, "target_refs": { "title": "Optional `[{object_type, object_id}, ...]` for graph wiring" }, "trigger_kind": { "enum": [ "manual", "event", "schedule", "webhook", "agent_requested", "api" ], "title": "Defaults from the definition", "type": "string" } }, "required": [ "run_key", "input" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Start workflow run (dry-run)", "tags": [ "workflows" ] } }, "/v1/actions/hospitality.action.start_workflow_run/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_start_workflow_run` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.start_workflow_run:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_start_workflow_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "expires_at": { "format": "date-time", "title": "Run timeout", "type": "string" }, "initiating_agent_installation_id": { "title": "Set when an installed agent initiated the run", "type": "string" }, "input": { "title": "Frozen, redacted start input" }, "run_key": { "title": "Host-supplied business / dedupe key", "type": "string" }, "target_refs": { "title": "Optional `[{object_type, object_id}, ...]` for graph wiring" }, "trigger_kind": { "enum": [ "manual", "event", "schedule", "webhook", "agent_requested", "api" ], "title": "Defaults from the definition", "type": "string" } }, "required": [ "run_key", "input" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_definition" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Start workflow run (rollup delta)", "tags": [ "workflows" ] } }, "/v1/actions/hospitality.action.store_lost_found_item/apply": { "post": { "description": "Put a found item away, or move it, saying where (`storage_location`). A found item becomes `stored`; a claimed one stays `claimed` with its new place. Storing it again in the same place is a no-op; a returned or disposed item is refused. Emits `lost_found_item.stored`.\n\nEffects: modify hospitality.lost_found_item.", "operationId": "apply_hospitality_action_store_lost_found_item", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "storage_location": { "title": "Where it is kept", "type": "string" } }, "required": [ "storage_location" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.lost_found_item" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.lost_found_item" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.store_lost_found_item:apply" ] } ], "summary": "Store lost & found item", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.store_lost_found_item/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_store_lost_found_item` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.store_lost_found_item:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_store_lost_found_item", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "storage_location": { "title": "Where it is kept", "type": "string" } }, "required": [ "storage_location" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.lost_found_item" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.lost_found_item" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Store lost & found item (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.store_lost_found_item/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_store_lost_found_item`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_store_lost_found_item", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "storage_location": { "title": "Where it is kept", "type": "string" } }, "required": [ "storage_location" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.lost_found_item" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Store lost & found item (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.store_lost_found_item/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_store_lost_found_item` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.store_lost_found_item:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_store_lost_found_item", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "storage_location": { "title": "Where it is kept", "type": "string" } }, "required": [ "storage_location" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.lost_found_item" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Store lost & found item (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.store_payment_card/apply": { "post": { "description": "Record a card the PSP has already tokenised, bound to the person who holds it or the reservation it guarantees. Validators reject: a PAN-shaped token (PCI-DSS 4.0 — tokenise upstream), a last4 that is not four digits, an expiry month outside 1-12, an expiry already in the past, a `physical` card with no cardholder, a `virtual` card with no reservation or with a cardholder it cannot have, and a second card carrying a token already stored against the same binding. A `virtual` card may carry the channel's `activation_date` and `funded_amount`; the card then records `activation_at`, the house's midnight on that date, which the virtual-card charge automation sweeps (`charge_virtual_card`). The processor Customer the card hangs off and the merchant account that may draw on it are not this verb's to say: the card rail records them, read off the processor (`record_saved_payment_card`), so a card stored here names neither.\n\nEffects: create hospitality.payment_card; link hospitality.link.payment_card_for_person; link hospitality.link.payment_card_for_reservation.", "operationId": "apply_hospitality_action_store_payment_card", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "activation_date": { "format": "date", "title": "A `virtual` card's activation date — the first day the channel lets the house charge it (the house's calendar)", "type": "string" }, "brand": { "enum": [ "visa", "mastercard", "amex", "discover", "diners", "jcb", "unionpay", "cartes_bancaires", "eftpos_au", "interac", "maestro", "unknown" ], "title": "Card scheme as the PSP reports it", "type": "string" }, "capture_kind": { "enum": [ "terminal", "keyed_by_staff", "guest_device", "imported" ], "title": "How the card reached the PSP — decides card-present interchange, chargeback liability, and whether the cardholder's presence satisfied SCA", "type": "string" }, "card_format": { "enum": [ "physical", "virtual" ], "title": "`physical` (a person's card, the default) or `virtual` (an OTA single-booking card)", "type": "string" }, "cardholder_name": { "title": "The payer's name as the pay page took it, for a page card with no cardholder person", "type": "string" }, "expiry_month": { "title": "Expiry month, 1-12", "type": "integer" }, "expiry_year": { "title": "Expiry year, four digits", "type": "integer" }, "funded_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "What the channel loaded a `virtual` card with — the most the house may charge it", "type": "object" }, "funding": { "enum": [ "credit", "debit", "prepaid", "unknown" ], "title": "What the card draws on, as the scheme reports it", "type": "string" }, "issuing_country": { "title": "Issuing country (ISO 3166-1 alpha-2)", "type": "string" }, "last4": { "title": "Last four glyphs of the card number", "type": "string" }, "network_fingerprint": { "title": "PSP-issued stable identifier for the underlying card number", "type": "string" }, "off_session_consent": { "title": "True when the cardholder authenticated with the stated intent that the property may charge this card later", "type": "boolean" }, "person_ref": { "format": "uuid", "title": "The cardholder. Required for a `physical` card; a `virtual` card has none.", "type": "string", "x-aerandil-references": "hospitality.person" }, "provider": { "title": "PSP holding the card (`stripe`, `adyen`)", "type": "string" }, "provider_card_ref": { "title": "The PSP's token for this card (Stripe PaymentMethod id, Adyen recurringDetailReference). Never a PAN.", "type": "string" }, "reservation_ref": { "format": "uuid", "title": "The booking this card guarantees. Required for a `virtual` card; optional for a guest's own card.", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "retain_until": { "format": "date", "title": "Storage-limitation clock (set per jurisdiction and purpose)", "type": "string" }, "source": { "enum": [ "guest_device_page" ], "title": "Where the off-session consent was given, when narrower than the cardholder's: `guest_device_page` (a booking's pay page — its terms cover the bookings the card is bound to). A `physical` page card may then omit `person_ref` when it names `reservation_ref`: its payer is not the booking's guest", "type": "string" }, "wallet": { "enum": [ "apple_pay", "google_pay", "samsung_pay", "link", "click_to_pay", "other" ], "title": "Wallet the card was presented through, when it was", "type": "string" } }, "required": [ "provider", "provider_card_ref", "brand", "last4", "expiry_month", "expiry_year", "capture_kind", "off_session_consent", "retain_until" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.payment_card_for_person", "hospitality.link.payment_card_for_reservation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.payment_card" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.store_payment_card:apply" ] } ], "summary": "Store payment card", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.store_payment_card/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_store_payment_card` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.store_payment_card:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_store_payment_card", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "activation_date": { "format": "date", "title": "A `virtual` card's activation date — the first day the channel lets the house charge it (the house's calendar)", "type": "string" }, "brand": { "enum": [ "visa", "mastercard", "amex", "discover", "diners", "jcb", "unionpay", "cartes_bancaires", "eftpos_au", "interac", "maestro", "unknown" ], "title": "Card scheme as the PSP reports it", "type": "string" }, "capture_kind": { "enum": [ "terminal", "keyed_by_staff", "guest_device", "imported" ], "title": "How the card reached the PSP — decides card-present interchange, chargeback liability, and whether the cardholder's presence satisfied SCA", "type": "string" }, "card_format": { "enum": [ "physical", "virtual" ], "title": "`physical` (a person's card, the default) or `virtual` (an OTA single-booking card)", "type": "string" }, "cardholder_name": { "title": "The payer's name as the pay page took it, for a page card with no cardholder person", "type": "string" }, "expiry_month": { "title": "Expiry month, 1-12", "type": "integer" }, "expiry_year": { "title": "Expiry year, four digits", "type": "integer" }, "funded_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "What the channel loaded a `virtual` card with — the most the house may charge it", "type": "object" }, "funding": { "enum": [ "credit", "debit", "prepaid", "unknown" ], "title": "What the card draws on, as the scheme reports it", "type": "string" }, "issuing_country": { "title": "Issuing country (ISO 3166-1 alpha-2)", "type": "string" }, "last4": { "title": "Last four glyphs of the card number", "type": "string" }, "network_fingerprint": { "title": "PSP-issued stable identifier for the underlying card number", "type": "string" }, "off_session_consent": { "title": "True when the cardholder authenticated with the stated intent that the property may charge this card later", "type": "boolean" }, "person_ref": { "format": "uuid", "title": "The cardholder. Required for a `physical` card; a `virtual` card has none.", "type": "string", "x-aerandil-references": "hospitality.person" }, "provider": { "title": "PSP holding the card (`stripe`, `adyen`)", "type": "string" }, "provider_card_ref": { "title": "The PSP's token for this card (Stripe PaymentMethod id, Adyen recurringDetailReference). Never a PAN.", "type": "string" }, "reservation_ref": { "format": "uuid", "title": "The booking this card guarantees. Required for a `virtual` card; optional for a guest's own card.", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "retain_until": { "format": "date", "title": "Storage-limitation clock (set per jurisdiction and purpose)", "type": "string" }, "source": { "enum": [ "guest_device_page" ], "title": "Where the off-session consent was given, when narrower than the cardholder's: `guest_device_page` (a booking's pay page — its terms cover the bookings the card is bound to). A `physical` page card may then omit `person_ref` when it names `reservation_ref`: its payer is not the booking's guest", "type": "string" }, "wallet": { "enum": [ "apple_pay", "google_pay", "samsung_pay", "link", "click_to_pay", "other" ], "title": "Wallet the card was presented through, when it was", "type": "string" } }, "required": [ "provider", "provider_card_ref", "brand", "last4", "expiry_month", "expiry_year", "capture_kind", "off_session_consent", "retain_until" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.payment_card_for_person", "hospitality.link.payment_card_for_reservation" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.payment_card" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Store payment card (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.store_payment_card/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_store_payment_card`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_store_payment_card", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "activation_date": { "format": "date", "title": "A `virtual` card's activation date — the first day the channel lets the house charge it (the house's calendar)", "type": "string" }, "brand": { "enum": [ "visa", "mastercard", "amex", "discover", "diners", "jcb", "unionpay", "cartes_bancaires", "eftpos_au", "interac", "maestro", "unknown" ], "title": "Card scheme as the PSP reports it", "type": "string" }, "capture_kind": { "enum": [ "terminal", "keyed_by_staff", "guest_device", "imported" ], "title": "How the card reached the PSP — decides card-present interchange, chargeback liability, and whether the cardholder's presence satisfied SCA", "type": "string" }, "card_format": { "enum": [ "physical", "virtual" ], "title": "`physical` (a person's card, the default) or `virtual` (an OTA single-booking card)", "type": "string" }, "cardholder_name": { "title": "The payer's name as the pay page took it, for a page card with no cardholder person", "type": "string" }, "expiry_month": { "title": "Expiry month, 1-12", "type": "integer" }, "expiry_year": { "title": "Expiry year, four digits", "type": "integer" }, "funded_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "What the channel loaded a `virtual` card with — the most the house may charge it", "type": "object" }, "funding": { "enum": [ "credit", "debit", "prepaid", "unknown" ], "title": "What the card draws on, as the scheme reports it", "type": "string" }, "issuing_country": { "title": "Issuing country (ISO 3166-1 alpha-2)", "type": "string" }, "last4": { "title": "Last four glyphs of the card number", "type": "string" }, "network_fingerprint": { "title": "PSP-issued stable identifier for the underlying card number", "type": "string" }, "off_session_consent": { "title": "True when the cardholder authenticated with the stated intent that the property may charge this card later", "type": "boolean" }, "person_ref": { "format": "uuid", "title": "The cardholder. Required for a `physical` card; a `virtual` card has none.", "type": "string", "x-aerandil-references": "hospitality.person" }, "provider": { "title": "PSP holding the card (`stripe`, `adyen`)", "type": "string" }, "provider_card_ref": { "title": "The PSP's token for this card (Stripe PaymentMethod id, Adyen recurringDetailReference). Never a PAN.", "type": "string" }, "reservation_ref": { "format": "uuid", "title": "The booking this card guarantees. Required for a `virtual` card; optional for a guest's own card.", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "retain_until": { "format": "date", "title": "Storage-limitation clock (set per jurisdiction and purpose)", "type": "string" }, "source": { "enum": [ "guest_device_page" ], "title": "Where the off-session consent was given, when narrower than the cardholder's: `guest_device_page` (a booking's pay page — its terms cover the bookings the card is bound to). A `physical` page card may then omit `person_ref` when it names `reservation_ref`: its payer is not the booking's guest", "type": "string" }, "wallet": { "enum": [ "apple_pay", "google_pay", "samsung_pay", "link", "click_to_pay", "other" ], "title": "Wallet the card was presented through, when it was", "type": "string" } }, "required": [ "provider", "provider_card_ref", "brand", "last4", "expiry_month", "expiry_year", "capture_kind", "off_session_consent", "retain_until" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Store payment card (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.store_payment_card/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_store_payment_card` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.store_payment_card:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_store_payment_card", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "activation_date": { "format": "date", "title": "A `virtual` card's activation date — the first day the channel lets the house charge it (the house's calendar)", "type": "string" }, "brand": { "enum": [ "visa", "mastercard", "amex", "discover", "diners", "jcb", "unionpay", "cartes_bancaires", "eftpos_au", "interac", "maestro", "unknown" ], "title": "Card scheme as the PSP reports it", "type": "string" }, "capture_kind": { "enum": [ "terminal", "keyed_by_staff", "guest_device", "imported" ], "title": "How the card reached the PSP — decides card-present interchange, chargeback liability, and whether the cardholder's presence satisfied SCA", "type": "string" }, "card_format": { "enum": [ "physical", "virtual" ], "title": "`physical` (a person's card, the default) or `virtual` (an OTA single-booking card)", "type": "string" }, "cardholder_name": { "title": "The payer's name as the pay page took it, for a page card with no cardholder person", "type": "string" }, "expiry_month": { "title": "Expiry month, 1-12", "type": "integer" }, "expiry_year": { "title": "Expiry year, four digits", "type": "integer" }, "funded_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "What the channel loaded a `virtual` card with — the most the house may charge it", "type": "object" }, "funding": { "enum": [ "credit", "debit", "prepaid", "unknown" ], "title": "What the card draws on, as the scheme reports it", "type": "string" }, "issuing_country": { "title": "Issuing country (ISO 3166-1 alpha-2)", "type": "string" }, "last4": { "title": "Last four glyphs of the card number", "type": "string" }, "network_fingerprint": { "title": "PSP-issued stable identifier for the underlying card number", "type": "string" }, "off_session_consent": { "title": "True when the cardholder authenticated with the stated intent that the property may charge this card later", "type": "boolean" }, "person_ref": { "format": "uuid", "title": "The cardholder. Required for a `physical` card; a `virtual` card has none.", "type": "string", "x-aerandil-references": "hospitality.person" }, "provider": { "title": "PSP holding the card (`stripe`, `adyen`)", "type": "string" }, "provider_card_ref": { "title": "The PSP's token for this card (Stripe PaymentMethod id, Adyen recurringDetailReference). Never a PAN.", "type": "string" }, "reservation_ref": { "format": "uuid", "title": "The booking this card guarantees. Required for a `virtual` card; optional for a guest's own card.", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "retain_until": { "format": "date", "title": "Storage-limitation clock (set per jurisdiction and purpose)", "type": "string" }, "source": { "enum": [ "guest_device_page" ], "title": "Where the off-session consent was given, when narrower than the cardholder's: `guest_device_page` (a booking's pay page — its terms cover the bookings the card is bound to). A `physical` page card may then omit `person_ref` when it names `reservation_ref`: its payer is not the booking's guest", "type": "string" }, "wallet": { "enum": [ "apple_pay", "google_pay", "samsung_pay", "link", "click_to_pay", "other" ], "title": "Wallet the card was presented through, when it was", "type": "string" } }, "required": [ "provider", "provider_card_ref", "brand", "last4", "expiry_month", "expiry_year", "capture_kind", "off_session_consent", "retain_until" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Store payment card (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.submit_owner_statement/apply": { "post": { "description": "Submit the target property's monthly owner statement — the USALI summary figures, the fee computation and the variance snapshot — for owner approval. Requires an active `management_agreement` covering the property (the statement links to it); a changes_requested statement is answered by resubmitting with `revision` + 1, never by editing. `external_ref` is the idempotency anchor.\n\nEffects: create hospitality.owner_statement; link hospitality.link.owner_statement_for_property; link hospitality.link.owner_statement_under_agreement.", "operationId": "apply_hospitality_action_submit_owner_statement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "base_fee": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Base management fee for the period", "type": "object" }, "due_by": { "format": "date", "title": "Contractual delivery deadline", "type": "string" }, "external_ref": { "title": "Idempotency anchor", "type": "string" }, "gop": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Gross operating profit (pre-management-fee)", "type": "object" }, "incentive_fee": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Incentive fee for the period (accrual or true-up)", "type": "object" }, "noi": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Net operating income for the period", "type": "object" }, "period_end": { "format": "date", "title": "Reporting-period end", "type": "string" }, "period_start": { "format": "date", "title": "Reporting-period start", "type": "string" }, "revision": { "title": "Revision number (defaults to 1)", "type": "integer" }, "submitted_at": { "format": "date-time", "title": "When the operator submitted — business time, not record time (defaults to now)", "type": "string" }, "total_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Total operating revenue for the period", "type": "object" }, "variance_snapshot": { "title": "Budget-vs-actual-vs-prior-year comparison, JSON" } }, "required": [ "period_start", "period_end", "due_by", "total_revenue", "gop", "base_fee", "noi" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.owner_statement_for_property", "hospitality.link.owner_statement_under_agreement" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.owner_statement" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.submit_owner_statement:apply" ] } ], "summary": "Submit owner statement", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.submit_owner_statement/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_submit_owner_statement` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.submit_owner_statement:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_submit_owner_statement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "base_fee": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Base management fee for the period", "type": "object" }, "due_by": { "format": "date", "title": "Contractual delivery deadline", "type": "string" }, "external_ref": { "title": "Idempotency anchor", "type": "string" }, "gop": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Gross operating profit (pre-management-fee)", "type": "object" }, "incentive_fee": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Incentive fee for the period (accrual or true-up)", "type": "object" }, "noi": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Net operating income for the period", "type": "object" }, "period_end": { "format": "date", "title": "Reporting-period end", "type": "string" }, "period_start": { "format": "date", "title": "Reporting-period start", "type": "string" }, "revision": { "title": "Revision number (defaults to 1)", "type": "integer" }, "submitted_at": { "format": "date-time", "title": "When the operator submitted — business time, not record time (defaults to now)", "type": "string" }, "total_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Total operating revenue for the period", "type": "object" }, "variance_snapshot": { "title": "Budget-vs-actual-vs-prior-year comparison, JSON" } }, "required": [ "period_start", "period_end", "due_by", "total_revenue", "gop", "base_fee", "noi" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.owner_statement_for_property", "hospitality.link.owner_statement_under_agreement" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.owner_statement" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Submit owner statement (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.submit_owner_statement/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_submit_owner_statement`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_submit_owner_statement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "base_fee": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Base management fee for the period", "type": "object" }, "due_by": { "format": "date", "title": "Contractual delivery deadline", "type": "string" }, "external_ref": { "title": "Idempotency anchor", "type": "string" }, "gop": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Gross operating profit (pre-management-fee)", "type": "object" }, "incentive_fee": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Incentive fee for the period (accrual or true-up)", "type": "object" }, "noi": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Net operating income for the period", "type": "object" }, "period_end": { "format": "date", "title": "Reporting-period end", "type": "string" }, "period_start": { "format": "date", "title": "Reporting-period start", "type": "string" }, "revision": { "title": "Revision number (defaults to 1)", "type": "integer" }, "submitted_at": { "format": "date-time", "title": "When the operator submitted — business time, not record time (defaults to now)", "type": "string" }, "total_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Total operating revenue for the period", "type": "object" }, "variance_snapshot": { "title": "Budget-vs-actual-vs-prior-year comparison, JSON" } }, "required": [ "period_start", "period_end", "due_by", "total_revenue", "gop", "base_fee", "noi" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Submit owner statement (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.submit_owner_statement/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_submit_owner_statement` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.submit_owner_statement:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_submit_owner_statement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "base_fee": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Base management fee for the period", "type": "object" }, "due_by": { "format": "date", "title": "Contractual delivery deadline", "type": "string" }, "external_ref": { "title": "Idempotency anchor", "type": "string" }, "gop": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Gross operating profit (pre-management-fee)", "type": "object" }, "incentive_fee": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Incentive fee for the period (accrual or true-up)", "type": "object" }, "noi": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Net operating income for the period", "type": "object" }, "period_end": { "format": "date", "title": "Reporting-period end", "type": "string" }, "period_start": { "format": "date", "title": "Reporting-period start", "type": "string" }, "revision": { "title": "Revision number (defaults to 1)", "type": "integer" }, "submitted_at": { "format": "date-time", "title": "When the operator submitted — business time, not record time (defaults to now)", "type": "string" }, "total_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Total operating revenue for the period", "type": "object" }, "variance_snapshot": { "title": "Budget-vs-actual-vs-prior-year comparison, JSON" } }, "required": [ "period_start", "period_end", "due_by", "total_revenue", "gop", "base_fee", "noi" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Submit owner statement (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.submit_property_budget/apply": { "post": { "description": "Submit the target property's annual operating budget for owner approval (contract band: Oct 15 – Dec 1 submissions). Creates the `property_budget` in `submitted`; the owner's approval gate transitions it (approved / objected). `external_ref` is the idempotency anchor.\n\nEffects: create hospitality.property_budget; link hospitality.link.property_budget_for_property.", "operationId": "apply_hospitality_action_submit_property_budget", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "budgeted_gop": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Budgeted gross operating profit", "type": "object" }, "budgeted_noi": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Budgeted net operating income", "type": "object" }, "budgeted_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Budgeted total operating revenue", "type": "object" }, "external_ref": { "title": "Idempotency anchor", "type": "string" }, "fiscal_year": { "title": "Fiscal year", "type": "integer" }, "submitted_at": { "format": "date-time", "title": "When the operator submitted — business time, not record time (defaults to now)", "type": "string" } }, "required": [ "fiscal_year", "budgeted_revenue", "budgeted_gop", "budgeted_noi" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.property_budget_for_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.property_budget" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.submit_property_budget:apply" ] } ], "summary": "Submit property budget", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.submit_property_budget/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_submit_property_budget` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.submit_property_budget:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_submit_property_budget", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "budgeted_gop": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Budgeted gross operating profit", "type": "object" }, "budgeted_noi": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Budgeted net operating income", "type": "object" }, "budgeted_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Budgeted total operating revenue", "type": "object" }, "external_ref": { "title": "Idempotency anchor", "type": "string" }, "fiscal_year": { "title": "Fiscal year", "type": "integer" }, "submitted_at": { "format": "date-time", "title": "When the operator submitted — business time, not record time (defaults to now)", "type": "string" } }, "required": [ "fiscal_year", "budgeted_revenue", "budgeted_gop", "budgeted_noi" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.property_budget_for_property" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.property_budget" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Submit property budget (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.submit_property_budget/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_submit_property_budget`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_submit_property_budget", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "budgeted_gop": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Budgeted gross operating profit", "type": "object" }, "budgeted_noi": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Budgeted net operating income", "type": "object" }, "budgeted_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Budgeted total operating revenue", "type": "object" }, "external_ref": { "title": "Idempotency anchor", "type": "string" }, "fiscal_year": { "title": "Fiscal year", "type": "integer" }, "submitted_at": { "format": "date-time", "title": "When the operator submitted — business time, not record time (defaults to now)", "type": "string" } }, "required": [ "fiscal_year", "budgeted_revenue", "budgeted_gop", "budgeted_noi" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Submit property budget (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.submit_property_budget/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_submit_property_budget` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.submit_property_budget:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_submit_property_budget", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "budgeted_gop": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Budgeted gross operating profit", "type": "object" }, "budgeted_noi": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Budgeted net operating income", "type": "object" }, "budgeted_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Budgeted total operating revenue", "type": "object" }, "external_ref": { "title": "Idempotency anchor", "type": "string" }, "fiscal_year": { "title": "Fiscal year", "type": "integer" }, "submitted_at": { "format": "date-time", "title": "When the operator submitted — business time, not record time (defaults to now)", "type": "string" } }, "required": [ "fiscal_year", "budgeted_revenue", "budgeted_gop", "budgeted_noi" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Submit property budget (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.sunset_retail_product_line/apply": { "post": { "description": "Stamp the sunset date on a retail product line. Soft validator (proposal 0004 §7) warns when individual retail_product_available_at_* placements remain active — sunset is upstream of delisting; the placements should be ended in the same operation.\n\nEffects: modify hospitality.retail_product_line.", "operationId": "apply_hospitality_action_sunset_retail_product_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "sunset_on": { "format": "date", "title": "Sunset date", "type": "string" } }, "required": [ "sunset_on" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.retail_product_line" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.retail_product_line" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.sunset_retail_product_line:apply" ] } ], "summary": "Sunset retail product line", "tags": [ "brand_venue" ] } }, "/v1/actions/hospitality.action.sunset_retail_product_line/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_sunset_retail_product_line` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.sunset_retail_product_line:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_sunset_retail_product_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "sunset_on": { "format": "date", "title": "Sunset date", "type": "string" } }, "required": [ "sunset_on" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.retail_product_line" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.retail_product_line" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Sunset retail product line (dry-run)", "tags": [ "brand_venue" ] } }, "/v1/actions/hospitality.action.sunset_retail_product_line/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_sunset_retail_product_line`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_sunset_retail_product_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "sunset_on": { "format": "date", "title": "Sunset date", "type": "string" } }, "required": [ "sunset_on" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.retail_product_line" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Sunset retail product line (dry-run)", "tags": [ "brand_venue" ] } }, "/v1/actions/hospitality.action.sunset_retail_product_line/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_sunset_retail_product_line` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.sunset_retail_product_line:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_sunset_retail_product_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "sunset_on": { "format": "date", "title": "Sunset date", "type": "string" } }, "required": [ "sunset_on" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.retail_product_line" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Sunset retail product line (rollup delta)", "tags": [ "brand_venue" ] } }, "/v1/actions/hospitality.action.supersede_package/apply": { "post": { "description": "Mint a new immutable `package_version` against the target package. The previous active version transitions to `superseded`; existing `package_sale` rows retain their frozen pin and are not re-priced.\n\nEffects: create hospitality.package_version; link hospitality.link.package_has_version; link hospitality.link.package_has_active_version; link hospitality.link.package_version_supersedes; modify hospitality.package_version; unlink hospitality.link.package_has_active_version.", "operationId": "apply_hospitality_action_supersede_package", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allocation_rule": { "enum": [ "pro_rata", "room_residual" ], "title": "New allocation rule", "type": "string" }, "content_snapshot": { "title": "Frozen component identities + per-version overrides at version-mint time (opaque JSON)" }, "contracted_price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "New wrapper price", "type": "object" }, "supersede_reason": { "title": "Operator note explaining the supersedence", "type": "string" } }, "required": [ "contracted_price", "allocation_rule", "content_snapshot" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.package" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.package_has_version", "hospitality.link.package_has_active_version", "hospitality.link.package_version_supersedes" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.package_version" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.supersede_package:apply" ] } ], "summary": "Supersede package", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.supersede_package/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_supersede_package` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.supersede_package:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_supersede_package", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allocation_rule": { "enum": [ "pro_rata", "room_residual" ], "title": "New allocation rule", "type": "string" }, "content_snapshot": { "title": "Frozen component identities + per-version overrides at version-mint time (opaque JSON)" }, "contracted_price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "New wrapper price", "type": "object" }, "supersede_reason": { "title": "Operator note explaining the supersedence", "type": "string" } }, "required": [ "contracted_price", "allocation_rule", "content_snapshot" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.package" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.package_has_version", "hospitality.link.package_has_active_version", "hospitality.link.package_version_supersedes" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.package_version" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Supersede package (dry-run)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.supersede_package/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_supersede_package`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_supersede_package", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allocation_rule": { "enum": [ "pro_rata", "room_residual" ], "title": "New allocation rule", "type": "string" }, "content_snapshot": { "title": "Frozen component identities + per-version overrides at version-mint time (opaque JSON)" }, "contracted_price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "New wrapper price", "type": "object" }, "supersede_reason": { "title": "Operator note explaining the supersedence", "type": "string" } }, "required": [ "contracted_price", "allocation_rule", "content_snapshot" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.package" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Supersede package (dry-run)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.supersede_package/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_supersede_package` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.supersede_package:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_supersede_package", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "allocation_rule": { "enum": [ "pro_rata", "room_residual" ], "title": "New allocation rule", "type": "string" }, "content_snapshot": { "title": "Frozen component identities + per-version overrides at version-mint time (opaque JSON)" }, "contracted_price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "New wrapper price", "type": "object" }, "supersede_reason": { "title": "Operator note explaining the supersedence", "type": "string" } }, "required": [ "contracted_price", "allocation_rule", "content_snapshot" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.package" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Supersede package (rollup delta)", "tags": [ "revenue" ] } }, "/v1/actions/hospitality.action.suspend_agent_installation/apply": { "post": { "description": "Suspend, revoke, disable, or expire an installation. Does not mutate historical events or completed step runs; future workflow steps that reference the installation are blocked by `agent_installation_enabled_before_use`.\n\nEffects: modify hospitality.agent_installation.", "operationId": "apply_hospitality_action_suspend_agent_installation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_at": { "format": "date-time", "title": "Defaults to now()", "type": "string" }, "new_status": { "enum": [ "requested", "enabled", "suspended", "revoked", "disabled", "expired" ], "title": "suspended | revoked | disabled | expired", "type": "string" }, "reason": { "title": "Required text reason", "type": "string" } }, "required": [ "new_status", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_installation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.agent_installation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.suspend_agent_installation:apply" ] } ], "summary": "Suspend agent installation", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.suspend_agent_installation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_suspend_agent_installation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.suspend_agent_installation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_suspend_agent_installation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_at": { "format": "date-time", "title": "Defaults to now()", "type": "string" }, "new_status": { "enum": [ "requested", "enabled", "suspended", "revoked", "disabled", "expired" ], "title": "suspended | revoked | disabled | expired", "type": "string" }, "reason": { "title": "Required text reason", "type": "string" } }, "required": [ "new_status", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_installation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.agent_installation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Suspend agent installation (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.suspend_agent_installation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_suspend_agent_installation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_suspend_agent_installation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_at": { "format": "date-time", "title": "Defaults to now()", "type": "string" }, "new_status": { "enum": [ "requested", "enabled", "suspended", "revoked", "disabled", "expired" ], "title": "suspended | revoked | disabled | expired", "type": "string" }, "reason": { "title": "Required text reason", "type": "string" } }, "required": [ "new_status", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_installation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Suspend agent installation (dry-run)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.suspend_agent_installation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_suspend_agent_installation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.suspend_agent_installation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_suspend_agent_installation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_at": { "format": "date-time", "title": "Defaults to now()", "type": "string" }, "new_status": { "enum": [ "requested", "enabled", "suspended", "revoked", "disabled", "expired" ], "title": "suspended | revoked | disabled | expired", "type": "string" }, "reason": { "title": "Required text reason", "type": "string" } }, "required": [ "new_status", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_installation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Suspend agent installation (rollup delta)", "tags": [ "agents" ] } }, "/v1/actions/hospitality.action.suspend_channel_connection/apply": { "post": { "description": "Record that the *partner* stopped the conduit, and why. SiteMinder gives a non-compliant partner 90 days to remediate and reserves immediate suspension for production-affecting issues, so this is a state an operator must be able to see and distinguish from our own pause: the clock and the remediation belong to the other side. Emits `channel_connection.suspended`.\n\nEffects: modify hospitality.channel_connection.", "operationId": "apply_hospitality_action_suspend_channel_connection", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "paused_reason": { "title": "What the partner said, and any remediation deadline", "type": "string" } }, "required": [ "paused_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.channel_connection" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.suspend_channel_connection:apply" ] } ], "summary": "Suspend channel connection", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.suspend_channel_connection/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_suspend_channel_connection` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.suspend_channel_connection:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_suspend_channel_connection", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "paused_reason": { "title": "What the partner said, and any remediation deadline", "type": "string" } }, "required": [ "paused_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.channel_connection" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Suspend channel connection (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.suspend_channel_connection/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_suspend_channel_connection`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_suspend_channel_connection", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "paused_reason": { "title": "What the partner said, and any remediation deadline", "type": "string" } }, "required": [ "paused_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Suspend channel connection (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.suspend_channel_connection/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_suspend_channel_connection` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.suspend_channel_connection:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_suspend_channel_connection", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "paused_reason": { "title": "What the partner said, and any remediation deadline", "type": "string" } }, "required": [ "paused_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Suspend channel connection (rollup delta)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.take_room_out_of_order/apply": { "post": { "description": "Block a room from inventory for a date window — burst pipe, refurbishment, seasonal closure. Deducts the room type's availability ledger for the blocked dates (the booking ceiling is sellable - out_of_order + oversell_limit) and records exactly which rows it touched, so release restores exactly those; dates already sold past the reduced ceiling are reported as displaced (overbooking exposure), never silently absorbed. Refuses while a guest is (or will still be) in the room — move_room first — and reports pre-check-in assignments into the window as a work list instead of silently unassigning them (check-in refuses an out-of-order room until each is re-roomed). Overlapping active blocks refuse; extend or release the existing block instead.\n\nEffects: create hospitality.room_status_block; link hospitality.link.room_status_block_for_room; modify hospitality.availability_day.", "operationId": "apply_hospitality_action_take_room_out_of_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "end_date": { "format": "date", "title": "Last blocked night (inclusive through-date; the night audit returns the room when this date closes)", "type": "string" }, "reason": { "title": "Why the room is blocked", "type": "string" }, "remarks": { "title": "Repair / handover remarks", "type": "string" }, "return_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Housekeeping status the room re-enters on release", "type": "string" }, "start_date": { "format": "date", "title": "First blocked night", "type": "string" } }, "required": [ "start_date", "end_date", "reason", "return_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.room_status_block_for_room" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.room_status_block", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.take_room_out_of_order:apply" ] } ], "summary": "Take room out of order", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.take_room_out_of_order/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_take_room_out_of_order` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.take_room_out_of_order:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_take_room_out_of_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "end_date": { "format": "date", "title": "Last blocked night (inclusive through-date; the night audit returns the room when this date closes)", "type": "string" }, "reason": { "title": "Why the room is blocked", "type": "string" }, "remarks": { "title": "Repair / handover remarks", "type": "string" }, "return_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Housekeeping status the room re-enters on release", "type": "string" }, "start_date": { "format": "date", "title": "First blocked night", "type": "string" } }, "required": [ "start_date", "end_date", "reason", "return_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.room_status_block_for_room" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.room_status_block", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Take room out of order (dry-run)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.take_room_out_of_order/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_take_room_out_of_order`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_take_room_out_of_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "end_date": { "format": "date", "title": "Last blocked night (inclusive through-date; the night audit returns the room when this date closes)", "type": "string" }, "reason": { "title": "Why the room is blocked", "type": "string" }, "remarks": { "title": "Repair / handover remarks", "type": "string" }, "return_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Housekeeping status the room re-enters on release", "type": "string" }, "start_date": { "format": "date", "title": "First blocked night", "type": "string" } }, "required": [ "start_date", "end_date", "reason", "return_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Take room out of order (dry-run)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.take_room_out_of_order/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_take_room_out_of_order` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.take_room_out_of_order:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_take_room_out_of_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "end_date": { "format": "date", "title": "Last blocked night (inclusive through-date; the night audit returns the room when this date closes)", "type": "string" }, "reason": { "title": "Why the room is blocked", "type": "string" }, "remarks": { "title": "Repair / handover remarks", "type": "string" }, "return_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Housekeeping status the room re-enters on release", "type": "string" }, "start_date": { "format": "date", "title": "First blocked night", "type": "string" } }, "required": [ "start_date", "end_date", "reason", "return_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Take room out of order (rollup delta)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.take_room_out_of_service/apply": { "post": { "description": "Flag a room for a date window without touching inventory — a cosmetic issue, preventive maintenance. The room stays sellable and assignable (the OPERA out-of-service semantics; it remains in the occupancy denominator), so this is an advisory signal for housekeeping and the desk, not a gate. Same block lifecycle as out-of-order: a required reason, an inclusive through-date the night audit honours, and a declared return_status.\n\nEffects: create hospitality.room_status_block; link hospitality.link.room_status_block_for_room; modify hospitality.availability_day.", "operationId": "apply_hospitality_action_take_room_out_of_service", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "end_date": { "format": "date", "title": "Last blocked night (inclusive through-date; the night audit returns the room when this date closes)", "type": "string" }, "reason": { "title": "Why the room is blocked", "type": "string" }, "remarks": { "title": "Repair / handover remarks", "type": "string" }, "return_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Housekeeping status the room re-enters on release", "type": "string" }, "start_date": { "format": "date", "title": "First blocked night", "type": "string" } }, "required": [ "start_date", "end_date", "reason", "return_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.room_status_block_for_room" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.room_status_block", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.take_room_out_of_service:apply" ] } ], "summary": "Take room out of service", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.take_room_out_of_service/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_take_room_out_of_service` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.take_room_out_of_service:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_take_room_out_of_service", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "end_date": { "format": "date", "title": "Last blocked night (inclusive through-date; the night audit returns the room when this date closes)", "type": "string" }, "reason": { "title": "Why the room is blocked", "type": "string" }, "remarks": { "title": "Repair / handover remarks", "type": "string" }, "return_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Housekeeping status the room re-enters on release", "type": "string" }, "start_date": { "format": "date", "title": "First blocked night", "type": "string" } }, "required": [ "start_date", "end_date", "reason", "return_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.room_status_block_for_room" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.room_status_block", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Take room out of service (dry-run)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.take_room_out_of_service/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_take_room_out_of_service`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_take_room_out_of_service", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "end_date": { "format": "date", "title": "Last blocked night (inclusive through-date; the night audit returns the room when this date closes)", "type": "string" }, "reason": { "title": "Why the room is blocked", "type": "string" }, "remarks": { "title": "Repair / handover remarks", "type": "string" }, "return_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Housekeeping status the room re-enters on release", "type": "string" }, "start_date": { "format": "date", "title": "First blocked night", "type": "string" } }, "required": [ "start_date", "end_date", "reason", "return_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Take room out of service (dry-run)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.take_room_out_of_service/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_take_room_out_of_service` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.take_room_out_of_service:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_take_room_out_of_service", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "end_date": { "format": "date", "title": "Last blocked night (inclusive through-date; the night audit returns the room when this date closes)", "type": "string" }, "reason": { "title": "Why the room is blocked", "type": "string" }, "remarks": { "title": "Repair / handover remarks", "type": "string" }, "return_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Housekeeping status the room re-enters on release", "type": "string" }, "start_date": { "format": "date", "title": "First blocked night", "type": "string" } }, "required": [ "start_date", "end_date", "reason", "return_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Take room out of service (rollup delta)", "tags": [ "inventory" ] } }, "/v1/actions/hospitality.action.terminate_management_agreement/apply": { "post": { "description": "End the target HMA — the recorded kind carries why (performance-test failure, sale of the property, for-cause default, or without-cause). Terminal; the agreement row stays as the audit record of the terms that governed.\n\nEffects: modify hospitality.management_agreement.", "operationId": "apply_hospitality_action_terminate_management_agreement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "terminated_on": { "format": "date", "title": "Termination effective date", "type": "string" }, "termination_kind": { "enum": [ "performance", "sale_of_property", "for_cause", "without_cause" ], "title": "Why the agreement ended", "type": "string" }, "termination_reason": { "title": "Free-text note", "type": "string" } }, "required": [ "termination_kind", "terminated_on" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.management_agreement" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.management_agreement" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.terminate_management_agreement:apply" ] } ], "summary": "Terminate management agreement", "tags": [ "management" ] } }, "/v1/actions/hospitality.action.terminate_management_agreement/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_terminate_management_agreement` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.terminate_management_agreement:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_terminate_management_agreement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "terminated_on": { "format": "date", "title": "Termination effective date", "type": "string" }, "termination_kind": { "enum": [ "performance", "sale_of_property", "for_cause", "without_cause" ], "title": "Why the agreement ended", "type": "string" }, "termination_reason": { "title": "Free-text note", "type": "string" } }, "required": [ "termination_kind", "terminated_on" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.management_agreement" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.management_agreement" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Terminate management agreement (dry-run)", "tags": [ "management" ] } }, "/v1/actions/hospitality.action.terminate_management_agreement/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_terminate_management_agreement`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_terminate_management_agreement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "terminated_on": { "format": "date", "title": "Termination effective date", "type": "string" }, "termination_kind": { "enum": [ "performance", "sale_of_property", "for_cause", "without_cause" ], "title": "Why the agreement ended", "type": "string" }, "termination_reason": { "title": "Free-text note", "type": "string" } }, "required": [ "termination_kind", "terminated_on" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.management_agreement" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Terminate management agreement (dry-run)", "tags": [ "management" ] } }, "/v1/actions/hospitality.action.terminate_management_agreement/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_terminate_management_agreement` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.terminate_management_agreement:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_terminate_management_agreement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "terminated_on": { "format": "date", "title": "Termination effective date", "type": "string" }, "termination_kind": { "enum": [ "performance", "sale_of_property", "for_cause", "without_cause" ], "title": "Why the agreement ended", "type": "string" }, "termination_reason": { "title": "Free-text note", "type": "string" } }, "required": [ "termination_kind", "terminated_on" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.management_agreement" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Terminate management agreement (rollup delta)", "tags": [ "management" ] } }, "/v1/actions/hospitality.action.transfer_booking_hold/apply": { "post": { "description": "Use the card hold the guest placed at booking as the stay's hold, instead of taking a second one at check-in. Targets the stay's folio; every completed `preauthorization` request on the booking behind it whose hold is still uncaptured (`pending`) on the booking's own account moves onto this folio, so the check-out capture takes it against what the stay owes. Ledger-neutral — a pending hold moves no balance. Refused when the folio is closed or void, hangs off no stay, is kept in another currency than the hold, or the booking has no such hold; a hold already on this folio changes nothing, so a repeated call is safe. Emits `payment.booking_hold_transferred.recorded` per hold moved.\n\nEffects: unlink hospitality.link.folio_has_payment; link hospitality.link.folio_has_payment.", "operationId": "apply_hospitality_action_transfer_booking_hold", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated", "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_payment" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.transfer_booking_hold:apply" ] } ], "summary": "Transfer booking hold", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.transfer_booking_hold/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_transfer_booking_hold` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.transfer_booking_hold:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_transfer_booking_hold", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated", "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_payment" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Transfer booking hold (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.transfer_booking_hold/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_transfer_booking_hold`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_transfer_booking_hold", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Transfer booking hold (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.transfer_booking_hold/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_transfer_booking_hold` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.transfer_booking_hold:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_transfer_booking_hold", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Transfer booking hold (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.transfer_charge/apply": { "post": { "description": "Transfer a charge from its current folio to a target folio. Emits a single event with both folio refs for atomic audit. Idempotent on (charge, target_folio, business_date).\n\nEffects: modify hospitality.charge; modify hospitality.folio; unlink hospitality.link.folio_has_charge; link hospitality.link.folio_has_charge.", "operationId": "apply_hospitality_action_transfer_charge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" }, "target_folio_id": { "format": "uuid", "title": "Target folio", "type": "string", "x-aerandil-references": "hospitality.folio" } }, "required": [ "target_folio_id", "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.charge" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated", "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_charge" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.charge", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.transfer_charge:apply" ] } ], "summary": "Transfer charge", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.transfer_charge/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_transfer_charge` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.transfer_charge:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_transfer_charge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" }, "target_folio_id": { "format": "uuid", "title": "Target folio", "type": "string", "x-aerandil-references": "hospitality.folio" } }, "required": [ "target_folio_id", "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.charge" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated", "linked" ] }, "link_type": { "enum": [ "hospitality.link.folio_has_charge" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.charge", "hospitality.folio" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Transfer charge (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.transfer_charge/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_transfer_charge`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_transfer_charge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" }, "target_folio_id": { "format": "uuid", "title": "Target folio", "type": "string", "x-aerandil-references": "hospitality.folio" } }, "required": [ "target_folio_id", "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.charge" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Transfer charge (dry-run)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.transfer_charge/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_transfer_charge` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.transfer_charge:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_transfer_charge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" }, "target_folio_id": { "format": "uuid", "title": "Target folio", "type": "string", "x-aerandil-references": "hospitality.folio" } }, "required": [ "target_folio_id", "business_date" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.charge" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Transfer charge (rollup delta)", "tags": [ "finance" ] } }, "/v1/actions/hospitality.action.transfer_legacy_membership/apply": { "post": { "description": "Transfer a legacy-lifetime membership to a successor person. Only valid when the underlying tier has `transferable = true` (Aman Founders' legacy shape). Updates `person_ref` on the membership, refreshes the `membership_for_person` link, and tags the membership's dependency_kind = transferred_legacy to preserve the original-Founder lineage in audit.\n\nEffects: modify hospitality.membership; link hospitality.link.membership_for_person; unlink hospitality.link.membership_for_person.", "operationId": "apply_hospitality_action_transfer_legacy_membership", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "successor_person_id": { "format": "uuid", "title": "Successor person", "type": "string", "x-aerandil-references": "hospitality.person" }, "transferred_at": { "format": "date-time", "title": "When the transfer took effect", "type": "string" } }, "required": [ "successor_person_id", "transferred_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.membership_for_person" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.membership" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.transfer_legacy_membership:apply" ] } ], "summary": "Transfer legacy membership", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.transfer_legacy_membership/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_transfer_legacy_membership` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.transfer_legacy_membership:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_transfer_legacy_membership", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "successor_person_id": { "format": "uuid", "title": "Successor person", "type": "string", "x-aerandil-references": "hospitality.person" }, "transferred_at": { "format": "date-time", "title": "When the transfer took effect", "type": "string" } }, "required": [ "successor_person_id", "transferred_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.membership_for_person" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.membership" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Transfer legacy membership (dry-run)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.transfer_legacy_membership/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_transfer_legacy_membership`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_transfer_legacy_membership", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "successor_person_id": { "format": "uuid", "title": "Successor person", "type": "string", "x-aerandil-references": "hospitality.person" }, "transferred_at": { "format": "date-time", "title": "When the transfer took effect", "type": "string" } }, "required": [ "successor_person_id", "transferred_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Transfer legacy membership (dry-run)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.transfer_legacy_membership/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_transfer_legacy_membership` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.transfer_legacy_membership:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_transfer_legacy_membership", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "successor_person_id": { "format": "uuid", "title": "Successor person", "type": "string", "x-aerandil-references": "hospitality.person" }, "transferred_at": { "format": "date-time", "title": "When the transfer took effect", "type": "string" } }, "required": [ "successor_person_id", "transferred_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Transfer legacy membership (rollup delta)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.transfer_stock/apply": { "post": { "description": "Move stock of a material from this store to another of the house's (to_store_id) — the stores room to a floor cupboard, the minibar cart to a room's minibar. Two `transfer` movements in one transaction, the issuing leg here and the receiving leg there (`stock_movement_transfer_from` names the first), each moving its own level. Refused when it would take this store below zero, unless it allows negative stock.\n\nEffects: create hospitality.stock_movement; create hospitality.stock_level; modify hospitality.stock_level; link hospitality.link.stock_movement_for_level; link hospitality.link.stock_level_for_material; link hospitality.link.stock_level_in_store; link hospitality.link.stock_movement_recorded_by; link hospitality.link.stock_movement_transfer_from.", "operationId": "apply_hospitality_action_transfer_stock", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "material_id": { "format": "uuid", "title": "The material", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "title": "How much moves, in the material's unit (more than zero)", "type": "string" }, "reason": { "title": "Why it moved", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When it happened (defaults to now; a handset queueing offline sends its own time; refused when more than five minutes ahead of the kernel's clock)", "type": "string" }, "to_store_id": { "format": "uuid", "title": "The store it moves to", "type": "string", "x-aerandil-references": "hospitality.stock_store" } }, "required": [ "material_id", "quantity", "to_store_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_store" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.stock_movement_for_level", "hospitality.link.stock_level_for_material", "hospitality.link.stock_level_in_store", "hospitality.link.stock_movement_recorded_by", "hospitality.link.stock_movement_transfer_from" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.stock_movement", "hospitality.stock_level" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.transfer_stock:apply" ] } ], "summary": "Transfer stock", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.transfer_stock/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_transfer_stock` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.transfer_stock:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_transfer_stock", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "material_id": { "format": "uuid", "title": "The material", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "title": "How much moves, in the material's unit (more than zero)", "type": "string" }, "reason": { "title": "Why it moved", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When it happened (defaults to now; a handset queueing offline sends its own time; refused when more than five minutes ahead of the kernel's clock)", "type": "string" }, "to_store_id": { "format": "uuid", "title": "The store it moves to", "type": "string", "x-aerandil-references": "hospitality.stock_store" } }, "required": [ "material_id", "quantity", "to_store_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_store" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.stock_movement_for_level", "hospitality.link.stock_level_for_material", "hospitality.link.stock_level_in_store", "hospitality.link.stock_movement_recorded_by", "hospitality.link.stock_movement_transfer_from" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.stock_movement", "hospitality.stock_level" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Transfer stock (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.transfer_stock/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_transfer_stock`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_transfer_stock", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "material_id": { "format": "uuid", "title": "The material", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "title": "How much moves, in the material's unit (more than zero)", "type": "string" }, "reason": { "title": "Why it moved", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When it happened (defaults to now; a handset queueing offline sends its own time; refused when more than five minutes ahead of the kernel's clock)", "type": "string" }, "to_store_id": { "format": "uuid", "title": "The store it moves to", "type": "string", "x-aerandil-references": "hospitality.stock_store" } }, "required": [ "material_id", "quantity", "to_store_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_store" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Transfer stock (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.transfer_stock/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_transfer_stock` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.transfer_stock:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_transfer_stock", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "material_id": { "format": "uuid", "title": "The material", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "title": "How much moves, in the material's unit (more than zero)", "type": "string" }, "reason": { "title": "Why it moved", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When it happened (defaults to now; a handset queueing offline sends its own time; refused when more than five minutes ahead of the kernel's clock)", "type": "string" }, "to_store_id": { "format": "uuid", "title": "The store it moves to", "type": "string", "x-aerandil-references": "hospitality.stock_store" } }, "required": [ "material_id", "quantity", "to_store_id" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_store" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Transfer stock (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.transition_venue_brand/apply": { "post": { "description": "Transition the target venue from one venue_brand to another, closing the existing `venue_has_brand` link with an `effective_to` and opening a new link with `effective_from`. Supersedes-not-mutates per design-spec §B.2 — the historical brand attachment stays queryable via `as_of` lookups.\n\nEffects: link hospitality.link.venue_has_brand; unlink hospitality.link.venue_has_brand.", "operationId": "apply_hospitality_action_transition_venue_brand", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "incoming_venue_brand_id": { "format": "uuid", "title": "Incoming venue brand", "type": "string", "x-aerandil-references": "hospitality.venue_brand" }, "outgoing_venue_brand_id": { "format": "uuid", "title": "Outgoing venue brand", "type": "string", "x-aerandil-references": "hospitality.venue_brand" }, "transition_at": { "format": "date-time", "title": "Transition timestamp (effective_to on outgoing; effective_from on incoming)", "type": "string" } }, "required": [ "outgoing_venue_brand_id", "incoming_venue_brand_id", "transition_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.venue_has_brand" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.transition_venue_brand:apply" ] } ], "summary": "Transition venue brand", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.transition_venue_brand/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_transition_venue_brand` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.transition_venue_brand:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_transition_venue_brand", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "incoming_venue_brand_id": { "format": "uuid", "title": "Incoming venue brand", "type": "string", "x-aerandil-references": "hospitality.venue_brand" }, "outgoing_venue_brand_id": { "format": "uuid", "title": "Outgoing venue brand", "type": "string", "x-aerandil-references": "hospitality.venue_brand" }, "transition_at": { "format": "date-time", "title": "Transition timestamp (effective_to on outgoing; effective_from on incoming)", "type": "string" } }, "required": [ "outgoing_venue_brand_id", "incoming_venue_brand_id", "transition_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "end_dated" ] }, "link_type": { "enum": [ "hospitality.link.venue_has_brand" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ] }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Transition venue brand (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.transition_venue_brand/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_transition_venue_brand`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_transition_venue_brand", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "incoming_venue_brand_id": { "format": "uuid", "title": "Incoming venue brand", "type": "string", "x-aerandil-references": "hospitality.venue_brand" }, "outgoing_venue_brand_id": { "format": "uuid", "title": "Outgoing venue brand", "type": "string", "x-aerandil-references": "hospitality.venue_brand" }, "transition_at": { "format": "date-time", "title": "Transition timestamp (effective_to on outgoing; effective_from on incoming)", "type": "string" } }, "required": [ "outgoing_venue_brand_id", "incoming_venue_brand_id", "transition_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Transition venue brand (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.transition_venue_brand/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_transition_venue_brand` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.transition_venue_brand:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_transition_venue_brand", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "incoming_venue_brand_id": { "format": "uuid", "title": "Incoming venue brand", "type": "string", "x-aerandil-references": "hospitality.venue_brand" }, "outgoing_venue_brand_id": { "format": "uuid", "title": "Outgoing venue brand", "type": "string", "x-aerandil-references": "hospitality.venue_brand" }, "transition_at": { "format": "date-time", "title": "Transition timestamp (effective_to on outgoing; effective_from on incoming)", "type": "string" } }, "required": [ "outgoing_venue_brand_id", "incoming_venue_brand_id", "transition_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Transition venue brand (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.triage_guest_message/apply": { "post": { "description": "Emit a typed triage against an inbound `guest_message`. Inserts a `message_triage` row in `suggested` state with an immutable `enrichment_snapshot` captured at issue time. Validators enforce: triage-for-inbound-only, recommended-action-in-operator-allowlist (when recommended_action_kind = chain_typed_action), injection-intent-escalation-only (forces escalate path on injection.suspected), PAN-redaction. Decision lifecycle flows through apply / reject / escalate / expire.\n\nEffects: create hospitality.message_triage; modify hospitality.guest_conversation; link hospitality.link.message_triage_for_message; link hospitality.link.message_triage_at_property; link hospitality.link.message_triage_superseded_by; modify hospitality.message_triage.", "operationId": "apply_hospitality_action_triage_guest_message", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "enrichment_snapshot": { "additionalProperties": true, "title": "Frozen context snapshot at issue time (struct as JSON)", "type": "object" }, "expires_at": { "format": "date-time", "title": "Triage expiry (default: issued_at + 4h, or 30min for urgency=critical)", "type": "string" }, "factors_considered": { "items": { "enum": [ "message_text", "conversation_history", "guest_profile", "reservation_context", "recognition_history", "recovery_history", "loyalty_tier", "time_of_day", "language_detected", "attachment_present", "prior_triage_history", "safety_keywords", "other" ], "type": "string" }, "title": "Signals that drove the triage", "type": "array" }, "intent_alternatives": { "title": "Top-k alternative intents with scores (JSON array of {intent, score})" }, "intent_confidence": { "enum": [ "low", "medium", "high" ], "title": "Confidence ordinal", "type": "string" }, "intent_confidence_score": { "format": "decimal", "title": "Calibrated probability (optional)", "type": "string" }, "intent_primary": { "enum": [ "booking.inquiry", "booking.modification", "booking.cancellation", "booking.confirmation_query", "complaint.cleanliness", "complaint.noise", "complaint.billing", "complaint.service", "complaint.food", "complaint.other", "service.amenities", "service.spa", "service.restaurant", "service.transport", "service.lost_and_found", "service.wake_up", "service.technical", "service.housekeeping", "service.in_room_dining", "service.other", "info.amenities", "info.directions", "info.payment_policy", "info.wifi", "info.hours", "info.other", "recognition.celebration", "safety.emergency", "marketing.feedback", "chitchat.general", "injection.suspected", "other.unclassified" ], "title": "Leaf intent", "type": "string" }, "policy_outcomes": { "items": { "enum": [ "pan_redacted", "phi_redacted", "tcpa_opt_out_detected", "gdpr_erasure_referenced", "whatsapp_window_outside", "voice_consent_missing", "injection_attempt_detected", "safety_keyword_matched", "none" ], "type": "string" }, "title": "Compliance flags observed during triage", "type": "array" }, "rationale_text": { "title": "Human-readable explanation", "type": "string" }, "recommended_action_kind": { "enum": [ "auto_respond", "chain_typed_action", "escalate_to_staff", "silent_acknowledge", "no_action" ], "title": "Apply-path discriminator", "type": "string" }, "recommended_action_params": { "additionalProperties": true, "title": "Proposed parameters for the chained action (JSON)", "type": "object" }, "recommended_action_ref": { "title": "API name of the chained action (when kind = chain_typed_action)", "type": "string" }, "recommended_response_text": { "title": "Drafted reply text (when kind = auto_respond)", "type": "string" }, "sentiment": { "enum": [ "negative", "neutral", "positive" ], "title": "Sentiment ordinal", "type": "string" }, "sentiment_score": { "format": "decimal", "title": "Calibrated sentiment score [-1, 1]", "type": "string" }, "urgency": { "enum": [ "low", "normal", "high", "critical" ], "title": "Urgency classification", "type": "string" } }, "required": [ "intent_primary", "intent_confidence", "sentiment", "urgency", "factors_considered", "recommended_action_kind", "rationale_text", "enrichment_snapshot", "policy_outcomes" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_message" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.message_triage_for_message", "hospitality.link.message_triage_at_property", "hospitality.link.message_triage_superseded_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.message_triage", "hospitality.guest_conversation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.triage_guest_message:apply" ] } ], "summary": "Triage guest message", "tags": [ "messaging" ] } }, "/v1/actions/hospitality.action.triage_guest_message/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_triage_guest_message` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.triage_guest_message:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_triage_guest_message", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "enrichment_snapshot": { "additionalProperties": true, "title": "Frozen context snapshot at issue time (struct as JSON)", "type": "object" }, "expires_at": { "format": "date-time", "title": "Triage expiry (default: issued_at + 4h, or 30min for urgency=critical)", "type": "string" }, "factors_considered": { "items": { "enum": [ "message_text", "conversation_history", "guest_profile", "reservation_context", "recognition_history", "recovery_history", "loyalty_tier", "time_of_day", "language_detected", "attachment_present", "prior_triage_history", "safety_keywords", "other" ], "type": "string" }, "title": "Signals that drove the triage", "type": "array" }, "intent_alternatives": { "title": "Top-k alternative intents with scores (JSON array of {intent, score})" }, "intent_confidence": { "enum": [ "low", "medium", "high" ], "title": "Confidence ordinal", "type": "string" }, "intent_confidence_score": { "format": "decimal", "title": "Calibrated probability (optional)", "type": "string" }, "intent_primary": { "enum": [ "booking.inquiry", "booking.modification", "booking.cancellation", "booking.confirmation_query", "complaint.cleanliness", "complaint.noise", "complaint.billing", "complaint.service", "complaint.food", "complaint.other", "service.amenities", "service.spa", "service.restaurant", "service.transport", "service.lost_and_found", "service.wake_up", "service.technical", "service.housekeeping", "service.in_room_dining", "service.other", "info.amenities", "info.directions", "info.payment_policy", "info.wifi", "info.hours", "info.other", "recognition.celebration", "safety.emergency", "marketing.feedback", "chitchat.general", "injection.suspected", "other.unclassified" ], "title": "Leaf intent", "type": "string" }, "policy_outcomes": { "items": { "enum": [ "pan_redacted", "phi_redacted", "tcpa_opt_out_detected", "gdpr_erasure_referenced", "whatsapp_window_outside", "voice_consent_missing", "injection_attempt_detected", "safety_keyword_matched", "none" ], "type": "string" }, "title": "Compliance flags observed during triage", "type": "array" }, "rationale_text": { "title": "Human-readable explanation", "type": "string" }, "recommended_action_kind": { "enum": [ "auto_respond", "chain_typed_action", "escalate_to_staff", "silent_acknowledge", "no_action" ], "title": "Apply-path discriminator", "type": "string" }, "recommended_action_params": { "additionalProperties": true, "title": "Proposed parameters for the chained action (JSON)", "type": "object" }, "recommended_action_ref": { "title": "API name of the chained action (when kind = chain_typed_action)", "type": "string" }, "recommended_response_text": { "title": "Drafted reply text (when kind = auto_respond)", "type": "string" }, "sentiment": { "enum": [ "negative", "neutral", "positive" ], "title": "Sentiment ordinal", "type": "string" }, "sentiment_score": { "format": "decimal", "title": "Calibrated sentiment score [-1, 1]", "type": "string" }, "urgency": { "enum": [ "low", "normal", "high", "critical" ], "title": "Urgency classification", "type": "string" } }, "required": [ "intent_primary", "intent_confidence", "sentiment", "urgency", "factors_considered", "recommended_action_kind", "rationale_text", "enrichment_snapshot", "policy_outcomes" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_message" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.message_triage_for_message", "hospitality.link.message_triage_at_property", "hospitality.link.message_triage_superseded_by" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.message_triage", "hospitality.guest_conversation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Triage guest message (dry-run)", "tags": [ "messaging" ] } }, "/v1/actions/hospitality.action.triage_guest_message/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_triage_guest_message`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_triage_guest_message", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "enrichment_snapshot": { "additionalProperties": true, "title": "Frozen context snapshot at issue time (struct as JSON)", "type": "object" }, "expires_at": { "format": "date-time", "title": "Triage expiry (default: issued_at + 4h, or 30min for urgency=critical)", "type": "string" }, "factors_considered": { "items": { "enum": [ "message_text", "conversation_history", "guest_profile", "reservation_context", "recognition_history", "recovery_history", "loyalty_tier", "time_of_day", "language_detected", "attachment_present", "prior_triage_history", "safety_keywords", "other" ], "type": "string" }, "title": "Signals that drove the triage", "type": "array" }, "intent_alternatives": { "title": "Top-k alternative intents with scores (JSON array of {intent, score})" }, "intent_confidence": { "enum": [ "low", "medium", "high" ], "title": "Confidence ordinal", "type": "string" }, "intent_confidence_score": { "format": "decimal", "title": "Calibrated probability (optional)", "type": "string" }, "intent_primary": { "enum": [ "booking.inquiry", "booking.modification", "booking.cancellation", "booking.confirmation_query", "complaint.cleanliness", "complaint.noise", "complaint.billing", "complaint.service", "complaint.food", "complaint.other", "service.amenities", "service.spa", "service.restaurant", "service.transport", "service.lost_and_found", "service.wake_up", "service.technical", "service.housekeeping", "service.in_room_dining", "service.other", "info.amenities", "info.directions", "info.payment_policy", "info.wifi", "info.hours", "info.other", "recognition.celebration", "safety.emergency", "marketing.feedback", "chitchat.general", "injection.suspected", "other.unclassified" ], "title": "Leaf intent", "type": "string" }, "policy_outcomes": { "items": { "enum": [ "pan_redacted", "phi_redacted", "tcpa_opt_out_detected", "gdpr_erasure_referenced", "whatsapp_window_outside", "voice_consent_missing", "injection_attempt_detected", "safety_keyword_matched", "none" ], "type": "string" }, "title": "Compliance flags observed during triage", "type": "array" }, "rationale_text": { "title": "Human-readable explanation", "type": "string" }, "recommended_action_kind": { "enum": [ "auto_respond", "chain_typed_action", "escalate_to_staff", "silent_acknowledge", "no_action" ], "title": "Apply-path discriminator", "type": "string" }, "recommended_action_params": { "additionalProperties": true, "title": "Proposed parameters for the chained action (JSON)", "type": "object" }, "recommended_action_ref": { "title": "API name of the chained action (when kind = chain_typed_action)", "type": "string" }, "recommended_response_text": { "title": "Drafted reply text (when kind = auto_respond)", "type": "string" }, "sentiment": { "enum": [ "negative", "neutral", "positive" ], "title": "Sentiment ordinal", "type": "string" }, "sentiment_score": { "format": "decimal", "title": "Calibrated sentiment score [-1, 1]", "type": "string" }, "urgency": { "enum": [ "low", "normal", "high", "critical" ], "title": "Urgency classification", "type": "string" } }, "required": [ "intent_primary", "intent_confidence", "sentiment", "urgency", "factors_considered", "recommended_action_kind", "rationale_text", "enrichment_snapshot", "policy_outcomes" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_message" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Triage guest message (dry-run)", "tags": [ "messaging" ] } }, "/v1/actions/hospitality.action.triage_guest_message/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_triage_guest_message` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.triage_guest_message:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_triage_guest_message", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "enrichment_snapshot": { "additionalProperties": true, "title": "Frozen context snapshot at issue time (struct as JSON)", "type": "object" }, "expires_at": { "format": "date-time", "title": "Triage expiry (default: issued_at + 4h, or 30min for urgency=critical)", "type": "string" }, "factors_considered": { "items": { "enum": [ "message_text", "conversation_history", "guest_profile", "reservation_context", "recognition_history", "recovery_history", "loyalty_tier", "time_of_day", "language_detected", "attachment_present", "prior_triage_history", "safety_keywords", "other" ], "type": "string" }, "title": "Signals that drove the triage", "type": "array" }, "intent_alternatives": { "title": "Top-k alternative intents with scores (JSON array of {intent, score})" }, "intent_confidence": { "enum": [ "low", "medium", "high" ], "title": "Confidence ordinal", "type": "string" }, "intent_confidence_score": { "format": "decimal", "title": "Calibrated probability (optional)", "type": "string" }, "intent_primary": { "enum": [ "booking.inquiry", "booking.modification", "booking.cancellation", "booking.confirmation_query", "complaint.cleanliness", "complaint.noise", "complaint.billing", "complaint.service", "complaint.food", "complaint.other", "service.amenities", "service.spa", "service.restaurant", "service.transport", "service.lost_and_found", "service.wake_up", "service.technical", "service.housekeeping", "service.in_room_dining", "service.other", "info.amenities", "info.directions", "info.payment_policy", "info.wifi", "info.hours", "info.other", "recognition.celebration", "safety.emergency", "marketing.feedback", "chitchat.general", "injection.suspected", "other.unclassified" ], "title": "Leaf intent", "type": "string" }, "policy_outcomes": { "items": { "enum": [ "pan_redacted", "phi_redacted", "tcpa_opt_out_detected", "gdpr_erasure_referenced", "whatsapp_window_outside", "voice_consent_missing", "injection_attempt_detected", "safety_keyword_matched", "none" ], "type": "string" }, "title": "Compliance flags observed during triage", "type": "array" }, "rationale_text": { "title": "Human-readable explanation", "type": "string" }, "recommended_action_kind": { "enum": [ "auto_respond", "chain_typed_action", "escalate_to_staff", "silent_acknowledge", "no_action" ], "title": "Apply-path discriminator", "type": "string" }, "recommended_action_params": { "additionalProperties": true, "title": "Proposed parameters for the chained action (JSON)", "type": "object" }, "recommended_action_ref": { "title": "API name of the chained action (when kind = chain_typed_action)", "type": "string" }, "recommended_response_text": { "title": "Drafted reply text (when kind = auto_respond)", "type": "string" }, "sentiment": { "enum": [ "negative", "neutral", "positive" ], "title": "Sentiment ordinal", "type": "string" }, "sentiment_score": { "format": "decimal", "title": "Calibrated sentiment score [-1, 1]", "type": "string" }, "urgency": { "enum": [ "low", "normal", "high", "critical" ], "title": "Urgency classification", "type": "string" } }, "required": [ "intent_primary", "intent_confidence", "sentiment", "urgency", "factors_considered", "recommended_action_kind", "rationale_text", "enrichment_snapshot", "policy_outcomes" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_message" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Triage guest message (rollup delta)", "tags": [ "messaging" ] } }, "/v1/actions/hospitality.action.unfreeze_membership/apply": { "post": { "description": "Resume the membership. Inverse of `freeze_membership`. Sets `access_status = active` and clears the subscription's `suspension_state` (to `none`).\n\nEffects: modify hospitality.membership; modify hospitality.membership_subscription.", "operationId": "apply_hospitality_action_unfreeze_membership", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "unfrozen_at": { "format": "date-time", "title": "When the unfreeze took effect", "type": "string" } }, "required": [ "unfrozen_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.membership", "hospitality.membership_subscription" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.unfreeze_membership:apply" ] } ], "summary": "Unfreeze membership", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.unfreeze_membership/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_unfreeze_membership` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.unfreeze_membership:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_unfreeze_membership", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "unfrozen_at": { "format": "date-time", "title": "When the unfreeze took effect", "type": "string" } }, "required": [ "unfrozen_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.membership", "hospitality.membership_subscription" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Unfreeze membership (dry-run)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.unfreeze_membership/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_unfreeze_membership`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_unfreeze_membership", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "unfrozen_at": { "format": "date-time", "title": "When the unfreeze took effect", "type": "string" } }, "required": [ "unfrozen_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Unfreeze membership (dry-run)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.unfreeze_membership/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_unfreeze_membership` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.unfreeze_membership:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_unfreeze_membership", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "unfrozen_at": { "format": "date-time", "title": "When the unfreeze took effect", "type": "string" } }, "required": [ "unfrozen_at" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Unfreeze membership (rollup delta)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.unmap_channel_inventory/apply": { "post": { "description": "Retire a code binding by closing it with `effective_to`. The conduit stops publishing that room type or rate plan and starts rejecting inbound reservations naming its code. The row is closed rather than deleted because reservations already taken under that code still have to resolve, and an operator asked 'what did this OTA code mean in March' needs an answer. Emits `channel_mapping.unmapped`.\n\nEffects: modify hospitality.channel_mapping.", "operationId": "apply_hospitality_action_unmap_channel_inventory", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_to": { "format": "date", "title": "Last date this binding applies (defaults to today)", "type": "string" }, "notes": { "title": "Why the binding was retired", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_mapping" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.channel_mapping" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.unmap_channel_inventory:apply" ] } ], "summary": "Unmap channel inventory", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.unmap_channel_inventory/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_unmap_channel_inventory` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.unmap_channel_inventory:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_unmap_channel_inventory", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_to": { "format": "date", "title": "Last date this binding applies (defaults to today)", "type": "string" }, "notes": { "title": "Why the binding was retired", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_mapping" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.channel_mapping" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Unmap channel inventory (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.unmap_channel_inventory/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_unmap_channel_inventory`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_unmap_channel_inventory", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_to": { "format": "date", "title": "Last date this binding applies (defaults to today)", "type": "string" }, "notes": { "title": "Why the binding was retired", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_mapping" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Unmap channel inventory (dry-run)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.unmap_channel_inventory/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_unmap_channel_inventory` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.unmap_channel_inventory:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_unmap_channel_inventory", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "effective_to": { "format": "date", "title": "Last date this binding applies (defaults to today)", "type": "string" }, "notes": { "title": "Why the binding was retired", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_mapping" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Unmap channel inventory (rollup delta)", "tags": [ "channel_manager" ] } }, "/v1/actions/hospitality.action.update_automation/apply": { "post": { "description": "Tune a `draft` or `paused` automation's parameters — display name, description, the object-set filter, the modified-property watch, the cron expression, the effect templates, execution mode, approval routing, and the cascade-depth guard. Structural identity (condition kind, effect kind, watched object type, effect action/function) is immutable — to change it, archive and redefine. Refused on an `active` or `archived` automation (pause first). Only provided parameters are patched. Emits `automation.updated`.\n\nEffects: modify hospitality.automation.", "operationId": "apply_hospitality_action_update_automation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "approval_policy_ref": { "title": "New approval policy ref", "type": "string" }, "cron_expression": { "title": "New cron schedule", "type": "string" }, "description_text": { "title": "New description", "type": "string" }, "display_name": { "title": "New human-readable name", "type": "string" }, "effect_notification_template": { "title": "New notification template (JSON)" }, "effect_params_template": { "additionalProperties": true, "title": "New effect-input template (JSON)", "type": "object" }, "execution_mode": { "enum": [ "per_object", "batch" ], "title": "New execution mode", "type": "string" }, "max_cascade_depth": { "title": "New cascade-depth guard", "type": "integer" }, "modified_property_watch": { "title": "New modified-property watch (JSON array)" }, "object_set_filter": { "title": "New watched-set filter (JSON)" }, "requires_approval": { "title": "New approval-routing flag", "type": "boolean" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.automation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.automation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.update_automation:apply" ] } ], "summary": "Update automation", "tags": [ "automation" ] } }, "/v1/actions/hospitality.action.update_automation/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_update_automation` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.update_automation:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_update_automation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "approval_policy_ref": { "title": "New approval policy ref", "type": "string" }, "cron_expression": { "title": "New cron schedule", "type": "string" }, "description_text": { "title": "New description", "type": "string" }, "display_name": { "title": "New human-readable name", "type": "string" }, "effect_notification_template": { "title": "New notification template (JSON)" }, "effect_params_template": { "additionalProperties": true, "title": "New effect-input template (JSON)", "type": "object" }, "execution_mode": { "enum": [ "per_object", "batch" ], "title": "New execution mode", "type": "string" }, "max_cascade_depth": { "title": "New cascade-depth guard", "type": "integer" }, "modified_property_watch": { "title": "New modified-property watch (JSON array)" }, "object_set_filter": { "title": "New watched-set filter (JSON)" }, "requires_approval": { "title": "New approval-routing flag", "type": "boolean" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.automation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.automation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Update automation (dry-run)", "tags": [ "automation" ] } }, "/v1/actions/hospitality.action.update_automation/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_update_automation`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_update_automation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "approval_policy_ref": { "title": "New approval policy ref", "type": "string" }, "cron_expression": { "title": "New cron schedule", "type": "string" }, "description_text": { "title": "New description", "type": "string" }, "display_name": { "title": "New human-readable name", "type": "string" }, "effect_notification_template": { "title": "New notification template (JSON)" }, "effect_params_template": { "additionalProperties": true, "title": "New effect-input template (JSON)", "type": "object" }, "execution_mode": { "enum": [ "per_object", "batch" ], "title": "New execution mode", "type": "string" }, "max_cascade_depth": { "title": "New cascade-depth guard", "type": "integer" }, "modified_property_watch": { "title": "New modified-property watch (JSON array)" }, "object_set_filter": { "title": "New watched-set filter (JSON)" }, "requires_approval": { "title": "New approval-routing flag", "type": "boolean" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.automation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Update automation (dry-run)", "tags": [ "automation" ] } }, "/v1/actions/hospitality.action.update_automation/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_update_automation` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.update_automation:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_update_automation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "approval_policy_ref": { "title": "New approval policy ref", "type": "string" }, "cron_expression": { "title": "New cron schedule", "type": "string" }, "description_text": { "title": "New description", "type": "string" }, "display_name": { "title": "New human-readable name", "type": "string" }, "effect_notification_template": { "title": "New notification template (JSON)" }, "effect_params_template": { "additionalProperties": true, "title": "New effect-input template (JSON)", "type": "object" }, "execution_mode": { "enum": [ "per_object", "batch" ], "title": "New execution mode", "type": "string" }, "max_cascade_depth": { "title": "New cascade-depth guard", "type": "integer" }, "modified_property_watch": { "title": "New modified-property watch (JSON array)" }, "object_set_filter": { "title": "New watched-set filter (JSON)" }, "requires_approval": { "title": "New approval-routing flag", "type": "boolean" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.automation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Update automation (rollup delta)", "tags": [ "automation" ] } }, "/v1/actions/hospitality.action.update_banquet_order_line/apply": { "post": { "description": "Change a line (any subset of its fields). Changing a line on an issued order marks the order `revised`; a posted or cancelled order's lines are frozen.\n\nEffects: modify hospitality.banquet_order_line; modify hospitality.banquet_event_order; unlink hospitality.link.banquet_order_line_for_service_item; link hospitality.link.banquet_order_line_for_service_item.", "operationId": "apply_hospitality_action_update_banquet_order_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "category": { "enum": [ "room_rental", "food", "beverage", "audio_visual", "equipment", "labour", "decor", "entertainment", "other" ], "title": "Section of the sheet", "type": "string" }, "description": { "title": "What the line is", "type": "string" }, "notes": { "title": "Line notes", "type": "string" }, "quantity": { "title": "Fixed quantity, or units per person (default 1)", "type": "integer" }, "quantity_basis": { "enum": [ "per_person", "fixed" ], "title": "per_person or fixed", "type": "string" }, "sequence": { "title": "Position on the sheet", "type": "integer" }, "serve_at": { "format": "date-time", "title": "When the line is served or set", "type": "string" }, "service_item_id": { "format": "uuid", "title": "The catalogue item behind the line", "type": "string", "x-aerandil-references": "hospitality.service_item" }, "unit_price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Price per unit, in the order's currency", "type": "object" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_order_line" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated", "linked" ] }, "link_type": { "enum": [ "hospitality.link.banquet_order_line_for_service_item" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.banquet_order_line", "hospitality.banquet_event_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.update_banquet_order_line:apply" ] } ], "summary": "Update banquet order line", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.update_banquet_order_line/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_update_banquet_order_line` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.update_banquet_order_line:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_update_banquet_order_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "category": { "enum": [ "room_rental", "food", "beverage", "audio_visual", "equipment", "labour", "decor", "entertainment", "other" ], "title": "Section of the sheet", "type": "string" }, "description": { "title": "What the line is", "type": "string" }, "notes": { "title": "Line notes", "type": "string" }, "quantity": { "title": "Fixed quantity, or units per person (default 1)", "type": "integer" }, "quantity_basis": { "enum": [ "per_person", "fixed" ], "title": "per_person or fixed", "type": "string" }, "sequence": { "title": "Position on the sheet", "type": "integer" }, "serve_at": { "format": "date-time", "title": "When the line is served or set", "type": "string" }, "service_item_id": { "format": "uuid", "title": "The catalogue item behind the line", "type": "string", "x-aerandil-references": "hospitality.service_item" }, "unit_price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Price per unit, in the order's currency", "type": "object" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_order_line" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "unlinked", "end_dated", "linked" ] }, "link_type": { "enum": [ "hospitality.link.banquet_order_line_for_service_item" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.banquet_order_line", "hospitality.banquet_event_order" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Update banquet order line (dry-run)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.update_banquet_order_line/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_update_banquet_order_line`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_update_banquet_order_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "category": { "enum": [ "room_rental", "food", "beverage", "audio_visual", "equipment", "labour", "decor", "entertainment", "other" ], "title": "Section of the sheet", "type": "string" }, "description": { "title": "What the line is", "type": "string" }, "notes": { "title": "Line notes", "type": "string" }, "quantity": { "title": "Fixed quantity, or units per person (default 1)", "type": "integer" }, "quantity_basis": { "enum": [ "per_person", "fixed" ], "title": "per_person or fixed", "type": "string" }, "sequence": { "title": "Position on the sheet", "type": "integer" }, "serve_at": { "format": "date-time", "title": "When the line is served or set", "type": "string" }, "service_item_id": { "format": "uuid", "title": "The catalogue item behind the line", "type": "string", "x-aerandil-references": "hospitality.service_item" }, "unit_price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Price per unit, in the order's currency", "type": "object" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_order_line" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Update banquet order line (dry-run)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.update_banquet_order_line/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_update_banquet_order_line` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.update_banquet_order_line:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_update_banquet_order_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "category": { "enum": [ "room_rental", "food", "beverage", "audio_visual", "equipment", "labour", "decor", "entertainment", "other" ], "title": "Section of the sheet", "type": "string" }, "description": { "title": "What the line is", "type": "string" }, "notes": { "title": "Line notes", "type": "string" }, "quantity": { "title": "Fixed quantity, or units per person (default 1)", "type": "integer" }, "quantity_basis": { "enum": [ "per_person", "fixed" ], "title": "per_person or fixed", "type": "string" }, "sequence": { "title": "Position on the sheet", "type": "integer" }, "serve_at": { "format": "date-time", "title": "When the line is served or set", "type": "string" }, "service_item_id": { "format": "uuid", "title": "The catalogue item behind the line", "type": "string", "x-aerandil-references": "hospitality.service_item" }, "unit_price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Price per unit, in the order's currency", "type": "object" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_order_line" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Update banquet order line (rollup delta)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.update_coaching_plan/apply": { "post": { "description": "Update the target coaching plan. Operators update coaching plans in coherent passes (a check-in cycle reviewing current focus, next review date, and protocol narrative together) rather than per-field; the action mirrors that operational shape.\n\nEffects: modify hospitality.coaching_plan.", "operationId": "apply_hospitality_action_update_coaching_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "current_focus_text": { "title": "Updated current focus", "type": "string" }, "is_active": { "title": "Active flag (set false to close the plan)", "type": "boolean" }, "next_review_date": { "format": "date", "title": "Updated next review date", "type": "string" }, "protocol_summary_text": { "title": "Updated running narrative", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.coaching_plan" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.coaching_plan" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.update_coaching_plan:apply" ] } ], "summary": "Update coaching plan", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.update_coaching_plan/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_update_coaching_plan` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.update_coaching_plan:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_update_coaching_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "current_focus_text": { "title": "Updated current focus", "type": "string" }, "is_active": { "title": "Active flag (set false to close the plan)", "type": "boolean" }, "next_review_date": { "format": "date", "title": "Updated next review date", "type": "string" }, "protocol_summary_text": { "title": "Updated running narrative", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.coaching_plan" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.coaching_plan" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Update coaching plan (dry-run)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.update_coaching_plan/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_update_coaching_plan`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_update_coaching_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "current_focus_text": { "title": "Updated current focus", "type": "string" }, "is_active": { "title": "Active flag (set false to close the plan)", "type": "boolean" }, "next_review_date": { "format": "date", "title": "Updated next review date", "type": "string" }, "protocol_summary_text": { "title": "Updated running narrative", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.coaching_plan" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Update coaching plan (dry-run)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.update_coaching_plan/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_update_coaching_plan` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.update_coaching_plan:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_update_coaching_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "current_focus_text": { "title": "Updated current focus", "type": "string" }, "is_active": { "title": "Active flag (set false to close the plan)", "type": "boolean" }, "next_review_date": { "format": "date", "title": "Updated next review date", "type": "string" }, "protocol_summary_text": { "title": "Updated running narrative", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.coaching_plan" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Update coaching plan (rollup delta)", "tags": [ "membership" ] } }, "/v1/actions/hospitality.action.update_company_billing/apply": { "post": { "description": "Edit the target company's billing party: billing address, tax identifier (the VAT number that makes the document usable for their input-tax recovery), registration number and invoicing email — accounts payable, never whoever made the booking. Every parameter is optional and at least one must be passed; omitted fields keep their values. Empty text clears the three scalars, and an address whose every field is blank clears the address; an address that is not blank must carry line 1, city and country. A call whose values all match is an idempotent no-op. The company's code, name and kind are not editable here — those decide who the account *is*, and a rename is not a billing correction. Emits `company.billing_updated` with the changed field names.\n\nEffects: modify hospitality.company.", "operationId": "apply_hospitality_action_update_company_billing", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "billing_address": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "title": "Company billing address", "type": "object" }, "invoicing_email": { "title": "Where this company's invoices are sent (empty clears)", "type": "string" }, "registration_number": { "title": "Company registration number (empty clears)", "type": "string" }, "tax_identifier": { "title": "VAT / tax registration number (empty clears)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.company" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.company" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.update_company_billing:apply" ] } ], "summary": "Update company billing details", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.update_company_billing/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_update_company_billing` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.update_company_billing:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_update_company_billing", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "billing_address": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "title": "Company billing address", "type": "object" }, "invoicing_email": { "title": "Where this company's invoices are sent (empty clears)", "type": "string" }, "registration_number": { "title": "Company registration number (empty clears)", "type": "string" }, "tax_identifier": { "title": "VAT / tax registration number (empty clears)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.company" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.company" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Update company billing details (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.update_company_billing/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_update_company_billing`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_update_company_billing", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "billing_address": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "title": "Company billing address", "type": "object" }, "invoicing_email": { "title": "Where this company's invoices are sent (empty clears)", "type": "string" }, "registration_number": { "title": "Company registration number (empty clears)", "type": "string" }, "tax_identifier": { "title": "VAT / tax registration number (empty clears)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.company" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Update company billing details (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.update_company_billing/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_update_company_billing` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.update_company_billing:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_update_company_billing", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "billing_address": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "title": "Company billing address", "type": "object" }, "invoicing_email": { "title": "Where this company's invoices are sent (empty clears)", "type": "string" }, "registration_number": { "title": "Company registration number (empty clears)", "type": "string" }, "tax_identifier": { "title": "VAT / tax registration number (empty clears)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.company" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Update company billing details (rollup delta)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.update_function_space/apply": { "post": { "description": "Change a function space's name, status, capacities or notes. At least one parameter must be given. Retiring or taking a space out of service leaves its booked events standing for the operator to move; the diary refuses new ones.\n\nEffects: modify hospitality.function_space.", "operationId": "apply_hospitality_action_update_function_space", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "area_sqm": { "format": "decimal", "title": "Floor area in square metres", "type": "string" }, "capacities": { "title": "Capacity per setup style: [{setup_style, capacity}]" }, "location": { "title": "Where in the house", "type": "string" }, "name": { "title": "Display name", "type": "string" }, "notes": { "title": "Operational notes", "type": "string" }, "status": { "enum": [ "active", "out_of_service", "retired" ], "title": "Space status", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_space" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.function_space" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.update_function_space:apply" ] } ], "summary": "Update function space", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.update_function_space/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_update_function_space` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.update_function_space:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_update_function_space", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "area_sqm": { "format": "decimal", "title": "Floor area in square metres", "type": "string" }, "capacities": { "title": "Capacity per setup style: [{setup_style, capacity}]" }, "location": { "title": "Where in the house", "type": "string" }, "name": { "title": "Display name", "type": "string" }, "notes": { "title": "Operational notes", "type": "string" }, "status": { "enum": [ "active", "out_of_service", "retired" ], "title": "Space status", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_space" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.function_space" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Update function space (dry-run)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.update_function_space/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_update_function_space`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_update_function_space", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "area_sqm": { "format": "decimal", "title": "Floor area in square metres", "type": "string" }, "capacities": { "title": "Capacity per setup style: [{setup_style, capacity}]" }, "location": { "title": "Where in the house", "type": "string" }, "name": { "title": "Display name", "type": "string" }, "notes": { "title": "Operational notes", "type": "string" }, "status": { "enum": [ "active", "out_of_service", "retired" ], "title": "Space status", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_space" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Update function space (dry-run)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.update_function_space/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_update_function_space` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.update_function_space:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_update_function_space", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "area_sqm": { "format": "decimal", "title": "Floor area in square metres", "type": "string" }, "capacities": { "title": "Capacity per setup style: [{setup_style, capacity}]" }, "location": { "title": "Where in the house", "type": "string" }, "name": { "title": "Display name", "type": "string" }, "notes": { "title": "Operational notes", "type": "string" }, "status": { "enum": [ "active", "out_of_service", "retired" ], "title": "Space status", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_space" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Update function space (rollup delta)", "tags": [ "catering" ] } }, "/v1/actions/hospitality.action.update_guest_profile/apply": { "post": { "description": "Edit the target guest's profile at the desk: names, email, phone, nationality, date of birth, postal address, tax identifier, and the room preferences (language, pillow, floor, quiet room, connecting rooms, dietary). Every parameter is optional and at least one must be passed; omitted fields keep their values. Empty text clears email, phone, nationality, tax identifier, language and pillow; an empty dietary list clears it; an address whose every field is blank clears the address; names cannot be cleared. An address that is not blank must carry line 1, city and country — the struct's own required fields, enforced here rather than left to arrive half-written. Preference edits merge into the existing struct, so the generated fields survive. A call whose values all match the current profile is an idempotent no-op. Recognition, ID documents, consent and merges keep their own verbs. Emits `person.profile_updated` with the changed field names.\n\nEffects: modify hospitality.person.", "operationId": "apply_hospitality_action_update_guest_profile", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "address": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "title": "Guest postal address", "type": "object" }, "connecting_room_ok": { "title": "Connecting rooms acceptable", "type": "boolean" }, "date_of_birth": { "format": "date", "title": "Date of birth", "type": "string" }, "dietary": { "items": { "type": "string" }, "title": "Dietary requirements (empty list clears)", "type": "array" }, "email": { "title": "Email (empty clears)", "type": "string" }, "family_name": { "title": "Family name", "type": "string" }, "given_name": { "title": "Given name", "type": "string" }, "language": { "title": "Preferred language (empty clears)", "type": "string" }, "nationality": { "title": "Nationality, ISO 3166-1 alpha-2 (empty clears)", "type": "string" }, "phone": { "title": "Phone (empty clears)", "type": "string" }, "pillow": { "title": "Pillow preference (empty clears)", "type": "string" }, "quiet_room": { "title": "Prefers a quiet room", "type": "boolean" }, "room_floor_preference": { "enum": [ "low", "mid", "high", "any" ], "title": "Floor preference", "type": "string" }, "tax_identifier": { "title": "Personal tax identifier, where a jurisdiction prints one on a guest's invoice (empty clears)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.person" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.update_guest_profile:apply" ] } ], "summary": "Update guest profile", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.update_guest_profile/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_update_guest_profile` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.update_guest_profile:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_update_guest_profile", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "address": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "title": "Guest postal address", "type": "object" }, "connecting_room_ok": { "title": "Connecting rooms acceptable", "type": "boolean" }, "date_of_birth": { "format": "date", "title": "Date of birth", "type": "string" }, "dietary": { "items": { "type": "string" }, "title": "Dietary requirements (empty list clears)", "type": "array" }, "email": { "title": "Email (empty clears)", "type": "string" }, "family_name": { "title": "Family name", "type": "string" }, "given_name": { "title": "Given name", "type": "string" }, "language": { "title": "Preferred language (empty clears)", "type": "string" }, "nationality": { "title": "Nationality, ISO 3166-1 alpha-2 (empty clears)", "type": "string" }, "phone": { "title": "Phone (empty clears)", "type": "string" }, "pillow": { "title": "Pillow preference (empty clears)", "type": "string" }, "quiet_room": { "title": "Prefers a quiet room", "type": "boolean" }, "room_floor_preference": { "enum": [ "low", "mid", "high", "any" ], "title": "Floor preference", "type": "string" }, "tax_identifier": { "title": "Personal tax identifier, where a jurisdiction prints one on a guest's invoice (empty clears)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.person" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Update guest profile (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.update_guest_profile/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_update_guest_profile`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_update_guest_profile", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "address": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "title": "Guest postal address", "type": "object" }, "connecting_room_ok": { "title": "Connecting rooms acceptable", "type": "boolean" }, "date_of_birth": { "format": "date", "title": "Date of birth", "type": "string" }, "dietary": { "items": { "type": "string" }, "title": "Dietary requirements (empty list clears)", "type": "array" }, "email": { "title": "Email (empty clears)", "type": "string" }, "family_name": { "title": "Family name", "type": "string" }, "given_name": { "title": "Given name", "type": "string" }, "language": { "title": "Preferred language (empty clears)", "type": "string" }, "nationality": { "title": "Nationality, ISO 3166-1 alpha-2 (empty clears)", "type": "string" }, "phone": { "title": "Phone (empty clears)", "type": "string" }, "pillow": { "title": "Pillow preference (empty clears)", "type": "string" }, "quiet_room": { "title": "Prefers a quiet room", "type": "boolean" }, "room_floor_preference": { "enum": [ "low", "mid", "high", "any" ], "title": "Floor preference", "type": "string" }, "tax_identifier": { "title": "Personal tax identifier, where a jurisdiction prints one on a guest's invoice (empty clears)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Update guest profile (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.update_guest_profile/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_update_guest_profile` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.update_guest_profile:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_update_guest_profile", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "address": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "title": "Guest postal address", "type": "object" }, "connecting_room_ok": { "title": "Connecting rooms acceptable", "type": "boolean" }, "date_of_birth": { "format": "date", "title": "Date of birth", "type": "string" }, "dietary": { "items": { "type": "string" }, "title": "Dietary requirements (empty list clears)", "type": "array" }, "email": { "title": "Email (empty clears)", "type": "string" }, "family_name": { "title": "Family name", "type": "string" }, "given_name": { "title": "Given name", "type": "string" }, "language": { "title": "Preferred language (empty clears)", "type": "string" }, "nationality": { "title": "Nationality, ISO 3166-1 alpha-2 (empty clears)", "type": "string" }, "phone": { "title": "Phone (empty clears)", "type": "string" }, "pillow": { "title": "Pillow preference (empty clears)", "type": "string" }, "quiet_room": { "title": "Prefers a quiet room", "type": "boolean" }, "room_floor_preference": { "enum": [ "low", "mid", "high", "any" ], "title": "Floor preference", "type": "string" }, "tax_identifier": { "title": "Personal tax identifier, where a jurisdiction prints one on a guest's invoice (empty clears)", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Update guest profile (rollup delta)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.update_pricing_strategy/apply": { "post": { "description": "Update a rate plan's pricing strategy and coherent derivation / yieldable fields together. The rate-plan validator rejects incoherent transitions.\n\nEffects: modify hospitality.rate_plan.", "operationId": "apply_hospitality_action_update_pricing_strategy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "derived_modifier_kind": { "enum": [ "percent", "absolute" ], "title": "Derived modifier kind (bar_grid only)", "type": "string" }, "pricing_strategy": { "enum": [ "bar_grid", "open_pricing", "hybrid", "static_contract" ], "title": "Pricing strategy", "type": "string" }, "yieldable": { "title": "Yieldable by revenue agent", "type": "boolean" } }, "required": [ "pricing_strategy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_plan" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.rate_plan" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.update_pricing_strategy:apply" ] } ], "summary": "Update pricing strategy", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.update_pricing_strategy/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_update_pricing_strategy` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.update_pricing_strategy:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_update_pricing_strategy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "derived_modifier_kind": { "enum": [ "percent", "absolute" ], "title": "Derived modifier kind (bar_grid only)", "type": "string" }, "pricing_strategy": { "enum": [ "bar_grid", "open_pricing", "hybrid", "static_contract" ], "title": "Pricing strategy", "type": "string" }, "yieldable": { "title": "Yieldable by revenue agent", "type": "boolean" } }, "required": [ "pricing_strategy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_plan" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.rate_plan" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Update pricing strategy (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.update_pricing_strategy/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_update_pricing_strategy`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_update_pricing_strategy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "derived_modifier_kind": { "enum": [ "percent", "absolute" ], "title": "Derived modifier kind (bar_grid only)", "type": "string" }, "pricing_strategy": { "enum": [ "bar_grid", "open_pricing", "hybrid", "static_contract" ], "title": "Pricing strategy", "type": "string" }, "yieldable": { "title": "Yieldable by revenue agent", "type": "boolean" } }, "required": [ "pricing_strategy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_plan" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Update pricing strategy (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.update_pricing_strategy/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_update_pricing_strategy` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.update_pricing_strategy:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_update_pricing_strategy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "derived_modifier_kind": { "enum": [ "percent", "absolute" ], "title": "Derived modifier kind (bar_grid only)", "type": "string" }, "pricing_strategy": { "enum": [ "bar_grid", "open_pricing", "hybrid", "static_contract" ], "title": "Pricing strategy", "type": "string" }, "yieldable": { "title": "Yieldable by revenue agent", "type": "boolean" } }, "required": [ "pricing_strategy" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_plan" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Update pricing strategy (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.update_service_philosophy/apply": { "post": { "description": "Upsert the property's service philosophy. Creates the philosophy row on first call, modifies on subsequent calls. Every axis is required so the philosophy is always fully specified — partial updates would let operators drift into half-set axes without intending to. The 1:1 `property_has_philosophy` link is established on first call and not re-linked on subsequent updates.\n\nEffects: create hospitality.service_philosophy; modify hospitality.service_philosophy; link hospitality.link.property_has_philosophy.", "operationId": "apply_hospitality_action_update_service_philosophy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "address_form_default": { "enum": [ "mr_ms", "first_name", "no_name" ], "title": "Address form default", "type": "string" }, "anticipatory_responsive": { "enum": [ "extremely_anticipatory", "anticipatory", "balanced", "responsive", "purely_responsive" ], "title": "Anticipatory ↔ responsive", "type": "string" }, "audit_target": { "enum": [ "forbes", "aaa_diamond", "lqa", "internal_only", "none" ], "title": "Audit target", "type": "string" }, "empowered_scripted": { "enum": [ "fully_empowered", "empowered_with_guidance", "balanced", "mostly_scripted", "fully_scripted" ], "title": "Empowered ↔ scripted", "type": "string" }, "ex_cx_priority": { "enum": [ "employees_first", "employees_above_guests", "employees_equal_guests", "guests_first", "investors_first" ], "title": "EX → CX priority", "type": "string" }, "hospitality_service_emphasis": { "enum": [ "hospitality_first", "balanced_warm", "professional_warmth", "service_efficient", "transactional" ], "title": "Hospitality ↔ service emphasis", "type": "string" }, "personality_presentation": { "enum": [ "muted", "forward", "as_product" ], "title": "Personality presentation", "type": "string" }, "philosophy_statement_text": { "title": "Narrative statement", "type": "string" }, "privacy_visibility_default": { "enum": [ "extremely_private_invisible_attention", "private", "balanced", "visible_attention", "extremely_visible" ], "title": "Privacy ↔ visibility default", "type": "string" }, "recognition_depth": { "enum": [ "minimal", "name_recognition", "preference_recognition", "relationship_recognition", "deep_recognition" ], "title": "Recognition depth", "type": "string" }, "recovery_culture_intent": { "title": "Recovery culture intent (self-declared)", "type": "string" }, "surface_register_default": { "enum": [ "formal_warm", "crafted_theatre", "quick_warm", "discreet_professional", "focused_coaching", "other" ], "title": "Surface register default", "type": "string" } }, "required": [ "anticipatory_responsive", "empowered_scripted", "surface_register_default", "address_form_default", "personality_presentation", "recognition_depth", "privacy_visibility_default", "hospitality_service_emphasis", "ex_cx_priority", "audit_target", "philosophy_statement_text" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.property_has_philosophy" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.service_philosophy" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.update_service_philosophy:apply" ] } ], "summary": "Update service philosophy", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.update_service_philosophy/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_update_service_philosophy` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.update_service_philosophy:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_update_service_philosophy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "address_form_default": { "enum": [ "mr_ms", "first_name", "no_name" ], "title": "Address form default", "type": "string" }, "anticipatory_responsive": { "enum": [ "extremely_anticipatory", "anticipatory", "balanced", "responsive", "purely_responsive" ], "title": "Anticipatory ↔ responsive", "type": "string" }, "audit_target": { "enum": [ "forbes", "aaa_diamond", "lqa", "internal_only", "none" ], "title": "Audit target", "type": "string" }, "empowered_scripted": { "enum": [ "fully_empowered", "empowered_with_guidance", "balanced", "mostly_scripted", "fully_scripted" ], "title": "Empowered ↔ scripted", "type": "string" }, "ex_cx_priority": { "enum": [ "employees_first", "employees_above_guests", "employees_equal_guests", "guests_first", "investors_first" ], "title": "EX → CX priority", "type": "string" }, "hospitality_service_emphasis": { "enum": [ "hospitality_first", "balanced_warm", "professional_warmth", "service_efficient", "transactional" ], "title": "Hospitality ↔ service emphasis", "type": "string" }, "personality_presentation": { "enum": [ "muted", "forward", "as_product" ], "title": "Personality presentation", "type": "string" }, "philosophy_statement_text": { "title": "Narrative statement", "type": "string" }, "privacy_visibility_default": { "enum": [ "extremely_private_invisible_attention", "private", "balanced", "visible_attention", "extremely_visible" ], "title": "Privacy ↔ visibility default", "type": "string" }, "recognition_depth": { "enum": [ "minimal", "name_recognition", "preference_recognition", "relationship_recognition", "deep_recognition" ], "title": "Recognition depth", "type": "string" }, "recovery_culture_intent": { "title": "Recovery culture intent (self-declared)", "type": "string" }, "surface_register_default": { "enum": [ "formal_warm", "crafted_theatre", "quick_warm", "discreet_professional", "focused_coaching", "other" ], "title": "Surface register default", "type": "string" } }, "required": [ "anticipatory_responsive", "empowered_scripted", "surface_register_default", "address_form_default", "personality_presentation", "recognition_depth", "privacy_visibility_default", "hospitality_service_emphasis", "ex_cx_priority", "audit_target", "philosophy_statement_text" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.property_has_philosophy" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified" ] }, "object_type": { "enum": [ "hospitality.service_philosophy" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Update service philosophy (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.update_service_philosophy/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_update_service_philosophy`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_update_service_philosophy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "address_form_default": { "enum": [ "mr_ms", "first_name", "no_name" ], "title": "Address form default", "type": "string" }, "anticipatory_responsive": { "enum": [ "extremely_anticipatory", "anticipatory", "balanced", "responsive", "purely_responsive" ], "title": "Anticipatory ↔ responsive", "type": "string" }, "audit_target": { "enum": [ "forbes", "aaa_diamond", "lqa", "internal_only", "none" ], "title": "Audit target", "type": "string" }, "empowered_scripted": { "enum": [ "fully_empowered", "empowered_with_guidance", "balanced", "mostly_scripted", "fully_scripted" ], "title": "Empowered ↔ scripted", "type": "string" }, "ex_cx_priority": { "enum": [ "employees_first", "employees_above_guests", "employees_equal_guests", "guests_first", "investors_first" ], "title": "EX → CX priority", "type": "string" }, "hospitality_service_emphasis": { "enum": [ "hospitality_first", "balanced_warm", "professional_warmth", "service_efficient", "transactional" ], "title": "Hospitality ↔ service emphasis", "type": "string" }, "personality_presentation": { "enum": [ "muted", "forward", "as_product" ], "title": "Personality presentation", "type": "string" }, "philosophy_statement_text": { "title": "Narrative statement", "type": "string" }, "privacy_visibility_default": { "enum": [ "extremely_private_invisible_attention", "private", "balanced", "visible_attention", "extremely_visible" ], "title": "Privacy ↔ visibility default", "type": "string" }, "recognition_depth": { "enum": [ "minimal", "name_recognition", "preference_recognition", "relationship_recognition", "deep_recognition" ], "title": "Recognition depth", "type": "string" }, "recovery_culture_intent": { "title": "Recovery culture intent (self-declared)", "type": "string" }, "surface_register_default": { "enum": [ "formal_warm", "crafted_theatre", "quick_warm", "discreet_professional", "focused_coaching", "other" ], "title": "Surface register default", "type": "string" } }, "required": [ "anticipatory_responsive", "empowered_scripted", "surface_register_default", "address_form_default", "personality_presentation", "recognition_depth", "privacy_visibility_default", "hospitality_service_emphasis", "ex_cx_priority", "audit_target", "philosophy_statement_text" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Update service philosophy (dry-run)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.update_service_philosophy/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_update_service_philosophy` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.update_service_philosophy:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_update_service_philosophy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "address_form_default": { "enum": [ "mr_ms", "first_name", "no_name" ], "title": "Address form default", "type": "string" }, "anticipatory_responsive": { "enum": [ "extremely_anticipatory", "anticipatory", "balanced", "responsive", "purely_responsive" ], "title": "Anticipatory ↔ responsive", "type": "string" }, "audit_target": { "enum": [ "forbes", "aaa_diamond", "lqa", "internal_only", "none" ], "title": "Audit target", "type": "string" }, "empowered_scripted": { "enum": [ "fully_empowered", "empowered_with_guidance", "balanced", "mostly_scripted", "fully_scripted" ], "title": "Empowered ↔ scripted", "type": "string" }, "ex_cx_priority": { "enum": [ "employees_first", "employees_above_guests", "employees_equal_guests", "guests_first", "investors_first" ], "title": "EX → CX priority", "type": "string" }, "hospitality_service_emphasis": { "enum": [ "hospitality_first", "balanced_warm", "professional_warmth", "service_efficient", "transactional" ], "title": "Hospitality ↔ service emphasis", "type": "string" }, "personality_presentation": { "enum": [ "muted", "forward", "as_product" ], "title": "Personality presentation", "type": "string" }, "philosophy_statement_text": { "title": "Narrative statement", "type": "string" }, "privacy_visibility_default": { "enum": [ "extremely_private_invisible_attention", "private", "balanced", "visible_attention", "extremely_visible" ], "title": "Privacy ↔ visibility default", "type": "string" }, "recognition_depth": { "enum": [ "minimal", "name_recognition", "preference_recognition", "relationship_recognition", "deep_recognition" ], "title": "Recognition depth", "type": "string" }, "recovery_culture_intent": { "title": "Recovery culture intent (self-declared)", "type": "string" }, "surface_register_default": { "enum": [ "formal_warm", "crafted_theatre", "quick_warm", "discreet_professional", "focused_coaching", "other" ], "title": "Surface register default", "type": "string" } }, "required": [ "anticipatory_responsive", "empowered_scripted", "surface_register_default", "address_form_default", "personality_presentation", "recognition_depth", "privacy_visibility_default", "hospitality_service_emphasis", "ex_cx_priority", "audit_target", "philosophy_statement_text" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Update service philosophy (rollup delta)", "tags": [ "organization" ] } }, "/v1/actions/hospitality.action.update_staff_member_profile/apply": { "post": { "description": "Update the target staff member's profile fields. Every parameter is optional but at least one must be provided; omitted fields keep their current values. `employee_id` is identity and cannot change here. A call whose values all match the current profile is an idempotent no-op (connector re-loads retry safely without version churn). Emits `staff.profile_updated`.\n\nEffects: modify hospitality.staff_member.", "operationId": "apply_hospitality_action_update_staff_member_profile", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "active": { "title": "Active", "type": "boolean" }, "contracted_weekly_hours": { "format": "decimal", "title": "Contracted hours a week (more than 0, at most 168)", "type": "string" }, "department": { "title": "Department", "type": "string" }, "discipline": { "enum": [ "front_office", "food_beverage", "culinary", "bar", "housekeeping", "engineering", "spa", "wellness_clinical", "wellness_coaching", "sales", "revenue", "management", "other" ], "title": "Discipline (coarse ladder for pathway definitions)", "type": "string" }, "email": { "title": "Email", "type": "string" }, "family_name": { "title": "Family name", "type": "string" }, "given_name": { "title": "Given name", "type": "string" }, "identity_subject": { "title": "Identity-provider subject (SSO) this employee signs in as", "type": "string" }, "most_recent_hire_date": { "format": "date", "title": "Most recent hire date", "type": "string" }, "role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "Role", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.staff_member" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.update_staff_member_profile:apply" ] } ], "summary": "Update staff member profile", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.update_staff_member_profile/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_update_staff_member_profile` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.update_staff_member_profile:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_update_staff_member_profile", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "active": { "title": "Active", "type": "boolean" }, "contracted_weekly_hours": { "format": "decimal", "title": "Contracted hours a week (more than 0, at most 168)", "type": "string" }, "department": { "title": "Department", "type": "string" }, "discipline": { "enum": [ "front_office", "food_beverage", "culinary", "bar", "housekeeping", "engineering", "spa", "wellness_clinical", "wellness_coaching", "sales", "revenue", "management", "other" ], "title": "Discipline (coarse ladder for pathway definitions)", "type": "string" }, "email": { "title": "Email", "type": "string" }, "family_name": { "title": "Family name", "type": "string" }, "given_name": { "title": "Given name", "type": "string" }, "identity_subject": { "title": "Identity-provider subject (SSO) this employee signs in as", "type": "string" }, "most_recent_hire_date": { "format": "date", "title": "Most recent hire date", "type": "string" }, "role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "Role", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.staff_member" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Update staff member profile (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.update_staff_member_profile/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_update_staff_member_profile`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_update_staff_member_profile", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "active": { "title": "Active", "type": "boolean" }, "contracted_weekly_hours": { "format": "decimal", "title": "Contracted hours a week (more than 0, at most 168)", "type": "string" }, "department": { "title": "Department", "type": "string" }, "discipline": { "enum": [ "front_office", "food_beverage", "culinary", "bar", "housekeeping", "engineering", "spa", "wellness_clinical", "wellness_coaching", "sales", "revenue", "management", "other" ], "title": "Discipline (coarse ladder for pathway definitions)", "type": "string" }, "email": { "title": "Email", "type": "string" }, "family_name": { "title": "Family name", "type": "string" }, "given_name": { "title": "Given name", "type": "string" }, "identity_subject": { "title": "Identity-provider subject (SSO) this employee signs in as", "type": "string" }, "most_recent_hire_date": { "format": "date", "title": "Most recent hire date", "type": "string" }, "role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "Role", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Update staff member profile (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.update_staff_member_profile/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_update_staff_member_profile` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.update_staff_member_profile:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_update_staff_member_profile", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "active": { "title": "Active", "type": "boolean" }, "contracted_weekly_hours": { "format": "decimal", "title": "Contracted hours a week (more than 0, at most 168)", "type": "string" }, "department": { "title": "Department", "type": "string" }, "discipline": { "enum": [ "front_office", "food_beverage", "culinary", "bar", "housekeeping", "engineering", "spa", "wellness_clinical", "wellness_coaching", "sales", "revenue", "management", "other" ], "title": "Discipline (coarse ladder for pathway definitions)", "type": "string" }, "email": { "title": "Email", "type": "string" }, "family_name": { "title": "Family name", "type": "string" }, "given_name": { "title": "Given name", "type": "string" }, "identity_subject": { "title": "Identity-provider subject (SSO) this employee signs in as", "type": "string" }, "most_recent_hire_date": { "format": "date", "title": "Most recent hire date", "type": "string" }, "role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "Role", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Update staff member profile (rollup delta)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.verify_staff_certification/apply": { "post": { "description": "Sign off a certification grant as verified, stamping the verifier principal and timestamp. Idempotent on an already-verified grant.\n\nEffects: modify hospitality.staff_certification.", "operationId": "apply_hospitality_action_verify_staff_certification", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_certification" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.staff_certification" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.verify_staff_certification:apply" ] } ], "summary": "Verify staff certification", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.verify_staff_certification/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_verify_staff_certification` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.verify_staff_certification:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_verify_staff_certification", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_certification" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.staff_certification" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Verify staff certification (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.verify_staff_certification/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_verify_staff_certification`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_verify_staff_certification", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_certification" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Verify staff certification (dry-run)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.verify_staff_certification/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_verify_staff_certification` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.verify_staff_certification:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_verify_staff_certification", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_certification" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Verify staff certification (rollup delta)", "tags": [ "people" ] } }, "/v1/actions/hospitality.action.void_brand_operator_cost/apply": { "post": { "description": "Void the target entry — terminal, the amount stays immutable as the audit record. Emits `brand_operator.cost_voided.decided` so the `daily_brand_operator` projection folds the amount back out.\n\nEffects: modify hospitality.brand_operator_cost_entry.", "operationId": "apply_hospitality_action_void_brand_operator_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.brand_operator_cost_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.brand_operator_cost_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.void_brand_operator_cost:apply" ] } ], "summary": "Void brand/operator cost", "tags": [ "brand_operator" ] } }, "/v1/actions/hospitality.action.void_brand_operator_cost/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_void_brand_operator_cost` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.void_brand_operator_cost:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_void_brand_operator_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.brand_operator_cost_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.brand_operator_cost_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Void brand/operator cost (dry-run)", "tags": [ "brand_operator" ] } }, "/v1/actions/hospitality.action.void_brand_operator_cost/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_void_brand_operator_cost`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_void_brand_operator_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.brand_operator_cost_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Void brand/operator cost (dry-run)", "tags": [ "brand_operator" ] } }, "/v1/actions/hospitality.action.void_brand_operator_cost/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_void_brand_operator_cost` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.void_brand_operator_cost:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_void_brand_operator_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.brand_operator_cost_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Void brand/operator cost (rollup delta)", "tags": [ "brand_operator" ] } }, "/v1/actions/hospitality.action.void_check_line/apply": { "post": { "description": "Remove an ENTERED line — one that has not fired to the kitchen. No product was made: no COGS, no sale, no authority gate; the reason code is the control (Restaurant365 / Square discipline). A fired or fulfilled line cannot be voided — that is a comp (`comp_check_line`), which is a P&L event. The line's modifier lines are voided with it; a modifier line is never voided alone. The check's totals drop by what was voided. Emits `fnb.line_voided`.\n\nEffects: modify hospitality.check_line; modify hospitality.guest_check.", "operationId": "apply_hospitality_action_void_check_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "enum": [ "guest_changed_mind", "entry_error", "item_unavailable", "long_wait", "duplicate", "other" ], "title": "Why the line is being voided", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.check_line" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.check_line", "hospitality.guest_check" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.void_check_line:apply" ] } ], "summary": "Void check line", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.void_check_line/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_void_check_line` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.void_check_line:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_void_check_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "enum": [ "guest_changed_mind", "entry_error", "item_unavailable", "long_wait", "duplicate", "other" ], "title": "Why the line is being voided", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.check_line" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.check_line", "hospitality.guest_check" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Void check line (dry-run)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.void_check_line/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_void_check_line`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_void_check_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "enum": [ "guest_changed_mind", "entry_error", "item_unavailable", "long_wait", "duplicate", "other" ], "title": "Why the line is being voided", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.check_line" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Void check line (dry-run)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.void_check_line/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_void_check_line` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.void_check_line:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_void_check_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "enum": [ "guest_changed_mind", "entry_error", "item_unavailable", "long_wait", "duplicate", "other" ], "title": "Why the line is being voided", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.check_line" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Void check line (rollup delta)", "tags": [ "fnb" ] } }, "/v1/actions/hospitality.action.void_labour_cost/apply": { "post": { "description": "Void the target labour ledger entry — terminal, the amount stays immutable as the audit record. Emits `labour.cost_voided.decided` so the `daily_labour` projection folds the amount back out.\n\nEffects: modify hospitality.labour_ledger_entry.", "operationId": "apply_hospitality_action_void_labour_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.labour_ledger_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.labour_ledger_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.void_labour_cost:apply" ] } ], "summary": "Void labour cost", "tags": [ "labour" ] } }, "/v1/actions/hospitality.action.void_labour_cost/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_void_labour_cost` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.void_labour_cost:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_void_labour_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.labour_ledger_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.labour_ledger_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Void labour cost (dry-run)", "tags": [ "labour" ] } }, "/v1/actions/hospitality.action.void_labour_cost/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_void_labour_cost`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_void_labour_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.labour_ledger_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Void labour cost (dry-run)", "tags": [ "labour" ] } }, "/v1/actions/hospitality.action.void_labour_cost/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_void_labour_cost` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.void_labour_cost:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_void_labour_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.labour_ledger_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Void labour cost (rollup delta)", "tags": [ "labour" ] } }, "/v1/actions/hospitality.action.void_shift/apply": { "post": { "description": "Mis-punch correction: void the target shift (open or closed) and re-record if needed — hours are never silently edited. Voiding a closed shift emits `labour.shift_voided.decided` so the `daily_labour` projection folds the hours back out; voiding a never-closed shift has no analytics impact.\n\nEffects: modify hospitality.staff_shift.", "operationId": "apply_hospitality_action_void_shift", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_shift" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.staff_shift" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.void_shift:apply" ] } ], "summary": "Void shift", "tags": [ "labour" ] } }, "/v1/actions/hospitality.action.void_shift/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_void_shift` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.void_shift:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_void_shift", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_shift" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.staff_shift" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Void shift (dry-run)", "tags": [ "labour" ] } }, "/v1/actions/hospitality.action.void_shift/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_void_shift`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_void_shift", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_shift" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Void shift (dry-run)", "tags": [ "labour" ] } }, "/v1/actions/hospitality.action.void_shift/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_void_shift` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.void_shift:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_void_shift", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_shift" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Void shift (rollup delta)", "tags": [ "labour" ] } }, "/v1/actions/hospitality.action.void_utility_cost/apply": { "post": { "description": "Void the target entry — terminal, the amounts stay immutable as the audit record. Emits `utility.cost_voided.decided` so the `daily_eww` projection folds the cost and consumption back out.\n\nEffects: modify hospitality.utility_ledger_entry.", "operationId": "apply_hospitality_action_void_utility_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.utility_ledger_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.utility_ledger_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.void_utility_cost:apply" ] } ], "summary": "Void utility cost", "tags": [ "eww" ] } }, "/v1/actions/hospitality.action.void_utility_cost/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_void_utility_cost` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.void_utility_cost:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_void_utility_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.utility_ledger_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.utility_ledger_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Void utility cost (dry-run)", "tags": [ "eww" ] } }, "/v1/actions/hospitality.action.void_utility_cost/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_void_utility_cost`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_void_utility_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.utility_ledger_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Void utility cost (dry-run)", "tags": [ "eww" ] } }, "/v1/actions/hospitality.action.void_utility_cost/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_void_utility_cost` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.void_utility_cost:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_void_utility_cost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Reason", "type": "string" } }, "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.utility_ledger_entry" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Void utility cost (rollup delta)", "tags": [ "eww" ] } }, "/v1/actions/hospitality.action.void_work_order/apply": { "post": { "description": "Withdraw an order raised in error, with the reason. Completed work is history and refuses. A held out-of-order block releases with the void — a withdrawn order never leaves the room silently blocked. Re-voiding is a no-op.\n\nEffects: modify hospitality.work_order; modify hospitality.room_status_block; modify hospitality.room; modify hospitality.availability_day.", "operationId": "apply_hospitality_action_void_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "void_reason": { "title": "Why the order is withdrawn", "type": "string" } }, "required": [ "void_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.work_order", "hospitality.room_status_block", "hospitality.room", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.void_work_order:apply" ] } ], "summary": "Void work order", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.void_work_order/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_void_work_order` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.void_work_order:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_void_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "void_reason": { "title": "Why the order is withdrawn", "type": "string" } }, "required": [ "void_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.work_order", "hospitality.room_status_block", "hospitality.room", "hospitality.availability_day" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Void work order (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.void_work_order/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_void_work_order`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_void_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "void_reason": { "title": "Why the order is withdrawn", "type": "string" } }, "required": [ "void_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Void work order (dry-run)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.void_work_order/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_void_work_order` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.void_work_order:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_void_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "void_reason": { "title": "Why the order is withdrawn", "type": "string" } }, "required": [ "void_reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Void work order (rollup delta)", "tags": [ "operations" ] } }, "/v1/actions/hospitality.action.waitlist_reservation_request/apply": { "post": { "description": "Record a reservation request the house cannot currently take. Mints a waitlist_entry holding the request (property, guest, room type, rate plan, dates, occupancy) plus the wait's own bookkeeping — `reason` for turnaway analysis, `priority` tier and `requested_at` for the working order, `telephone` for the call-to-confirm flow. Runs no availability check by design: the request is on the list precisely because it did not clear. Consumes nothing — no availability consumer traverses a waitlist entry — so a waitlisted request cannot oversell the house or distort pace. The night audit expires the entry two business days after its requested departure.\n\nEffects: create hospitality.waitlist_entry; link hospitality.link.waitlist_entry_for_property; link hospitality.link.waitlist_entry_for_guest; link hospitality.link.waitlist_entry_for_room_type; link hospitality.link.waitlist_entry_for_rate_plan.", "operationId": "apply_hospitality_action_waitlist_reservation_request", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults": { "title": "Adults", "type": "integer" }, "arrival_date": { "format": "date", "title": "Requested arrival", "type": "string" }, "children": { "title": "Children", "type": "integer" }, "departure_date": { "format": "date", "title": "Requested departure", "type": "string" }, "guest_id": { "format": "uuid", "title": "Guest", "type": "string", "x-aerandil-references": "hospitality.person" }, "notes": { "title": "Desk notes on the request", "type": "string" }, "priority": { "enum": [ "high", "normal", "low" ], "title": "Priority tier (defaults to normal; FIFO applies within a tier)", "type": "string" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "quoted_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Rate quoted when the request was taken (indicative only)", "type": "object" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan quoted against", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "reason": { "enum": [ "sold_out", "room_type_unavailable", "rate_unavailable", "restriction", "guest_request" ], "title": "Why the request could not be booked", "type": "string" }, "requested_at": { "format": "date-time", "title": "When the guest asked (defaults to now; must not be in the future)", "type": "string" }, "room_type_id": { "format": "uuid", "title": "Room type asked for", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "telephone": { "title": "Number to call when the room frees", "type": "string" } }, "required": [ "property_id", "guest_id", "room_type_id", "rate_plan_id", "arrival_date", "departure_date", "adults", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.waitlist_entry_for_property", "hospitality.link.waitlist_entry_for_guest", "hospitality.link.waitlist_entry_for_room_type", "hospitality.link.waitlist_entry_for_rate_plan" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.waitlist_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.waitlist_reservation_request:apply" ] } ], "summary": "Waitlist reservation request", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.waitlist_reservation_request/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_waitlist_reservation_request` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.waitlist_reservation_request:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_waitlist_reservation_request", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults": { "title": "Adults", "type": "integer" }, "arrival_date": { "format": "date", "title": "Requested arrival", "type": "string" }, "children": { "title": "Children", "type": "integer" }, "departure_date": { "format": "date", "title": "Requested departure", "type": "string" }, "guest_id": { "format": "uuid", "title": "Guest", "type": "string", "x-aerandil-references": "hospitality.person" }, "notes": { "title": "Desk notes on the request", "type": "string" }, "priority": { "enum": [ "high", "normal", "low" ], "title": "Priority tier (defaults to normal; FIFO applies within a tier)", "type": "string" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "quoted_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Rate quoted when the request was taken (indicative only)", "type": "object" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan quoted against", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "reason": { "enum": [ "sold_out", "room_type_unavailable", "rate_unavailable", "restriction", "guest_request" ], "title": "Why the request could not be booked", "type": "string" }, "requested_at": { "format": "date-time", "title": "When the guest asked (defaults to now; must not be in the future)", "type": "string" }, "room_type_id": { "format": "uuid", "title": "Room type asked for", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "telephone": { "title": "Number to call when the room frees", "type": "string" } }, "required": [ "property_id", "guest_id", "room_type_id", "rate_plan_id", "arrival_date", "departure_date", "adults", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked" ] }, "link_type": { "enum": [ "hospitality.link.waitlist_entry_for_property", "hospitality.link.waitlist_entry_for_guest", "hospitality.link.waitlist_entry_for_room_type", "hospitality.link.waitlist_entry_for_rate_plan" ] }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created" ] }, "object_type": { "enum": [ "hospitality.waitlist_entry" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Waitlist reservation request (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.waitlist_reservation_request/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_waitlist_reservation_request`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_waitlist_reservation_request", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults": { "title": "Adults", "type": "integer" }, "arrival_date": { "format": "date", "title": "Requested arrival", "type": "string" }, "children": { "title": "Children", "type": "integer" }, "departure_date": { "format": "date", "title": "Requested departure", "type": "string" }, "guest_id": { "format": "uuid", "title": "Guest", "type": "string", "x-aerandil-references": "hospitality.person" }, "notes": { "title": "Desk notes on the request", "type": "string" }, "priority": { "enum": [ "high", "normal", "low" ], "title": "Priority tier (defaults to normal; FIFO applies within a tier)", "type": "string" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "quoted_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Rate quoted when the request was taken (indicative only)", "type": "object" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan quoted against", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "reason": { "enum": [ "sold_out", "room_type_unavailable", "rate_unavailable", "restriction", "guest_request" ], "title": "Why the request could not be booked", "type": "string" }, "requested_at": { "format": "date-time", "title": "When the guest asked (defaults to now; must not be in the future)", "type": "string" }, "room_type_id": { "format": "uuid", "title": "Room type asked for", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "telephone": { "title": "Number to call when the room frees", "type": "string" } }, "required": [ "property_id", "guest_id", "room_type_id", "rate_plan_id", "arrival_date", "departure_date", "adults", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Waitlist reservation request (dry-run)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.waitlist_reservation_request/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_waitlist_reservation_request` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.waitlist_reservation_request:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_waitlist_reservation_request", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "adults": { "title": "Adults", "type": "integer" }, "arrival_date": { "format": "date", "title": "Requested arrival", "type": "string" }, "children": { "title": "Children", "type": "integer" }, "departure_date": { "format": "date", "title": "Requested departure", "type": "string" }, "guest_id": { "format": "uuid", "title": "Guest", "type": "string", "x-aerandil-references": "hospitality.person" }, "notes": { "title": "Desk notes on the request", "type": "string" }, "priority": { "enum": [ "high", "normal", "low" ], "title": "Priority tier (defaults to normal; FIFO applies within a tier)", "type": "string" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "quoted_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Rate quoted when the request was taken (indicative only)", "type": "object" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan quoted against", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "reason": { "enum": [ "sold_out", "room_type_unavailable", "rate_unavailable", "restriction", "guest_request" ], "title": "Why the request could not be booked", "type": "string" }, "requested_at": { "format": "date-time", "title": "When the guest asked (defaults to now; must not be in the future)", "type": "string" }, "room_type_id": { "format": "uuid", "title": "Room type asked for", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "telephone": { "title": "Number to call when the room frees", "type": "string" } }, "required": [ "property_id", "guest_id", "room_type_id", "rate_plan_id", "arrival_date", "departure_date", "adults", "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Waitlist reservation request (rollup delta)", "tags": [ "booking" ] } }, "/v1/actions/hospitality.action.withdraw_federated_participant/apply": { "post": { "description": "Pause or withdraw a participant prospectively. Sets withdrawal status and `withdrawal_effective_at`. Future runs whose collection starts after the effective time exclude the participant; already published aggregate outputs are NOT surgically removed (proposal §10.6). Open runs may be re-evaluated when `quarantine_open_runs = true`.\n\nEffects: modify hospitality.federated_participation.", "operationId": "apply_hospitality_action_withdraw_federated_participant", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "new_status": { "enum": [ "paused", "withdrawn", "revoked" ], "title": "paused | withdrawn | revoked", "type": "string" }, "quarantine_open_runs": { "title": "Whether to re-evaluate runs already in collection", "type": "boolean" }, "withdrawal_effective_at": { "format": "date-time", "title": "Prospective exclusion point; defaults to now()", "type": "string" }, "withdrawal_reason": { "title": "Optional bounded text", "type": "string" } }, "required": [ "new_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_participation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.federated_participation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.withdraw_federated_participant:apply" ] } ], "summary": "Withdraw federated participant", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.withdraw_federated_participant/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_withdraw_federated_participant` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.withdraw_federated_participant:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_withdraw_federated_participant", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "new_status": { "enum": [ "paused", "withdrawn", "revoked" ], "title": "paused | withdrawn | revoked", "type": "string" }, "quarantine_open_runs": { "title": "Whether to re-evaluate runs already in collection", "type": "boolean" }, "withdrawal_effective_at": { "format": "date-time", "title": "Prospective exclusion point; defaults to now()", "type": "string" }, "withdrawal_reason": { "title": "Optional bounded text", "type": "string" } }, "required": [ "new_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_participation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.federated_participation" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Withdraw federated participant (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.withdraw_federated_participant/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_withdraw_federated_participant`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_withdraw_federated_participant", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "new_status": { "enum": [ "paused", "withdrawn", "revoked" ], "title": "paused | withdrawn | revoked", "type": "string" }, "quarantine_open_runs": { "title": "Whether to re-evaluate runs already in collection", "type": "boolean" }, "withdrawal_effective_at": { "format": "date-time", "title": "Prospective exclusion point; defaults to now()", "type": "string" }, "withdrawal_reason": { "title": "Optional bounded text", "type": "string" } }, "required": [ "new_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_participation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Withdraw federated participant (dry-run)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.withdraw_federated_participant/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_withdraw_federated_participant` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.withdraw_federated_participant:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_withdraw_federated_participant", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "new_status": { "enum": [ "paused", "withdrawn", "revoked" ], "title": "paused | withdrawn | revoked", "type": "string" }, "quarantine_open_runs": { "title": "Whether to re-evaluate runs already in collection", "type": "boolean" }, "withdrawal_effective_at": { "format": "date-time", "title": "Prospective exclusion point; defaults to now()", "type": "string" }, "withdrawal_reason": { "title": "Optional bounded text", "type": "string" } }, "required": [ "new_status" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_participation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Withdraw federated participant (rollup delta)", "tags": [ "federated_intelligence" ] } }, "/v1/actions/hospitality.action.withdraw_fraud_signal/apply": { "post": { "description": "Take one of this house's contributions back out of Watchtower — a dispute later reversed, an outcome recorded against the wrong card. The contribution moves to `withdrawn` with the reason, and the card rail stops counting its digests in the network's answers. Forward-only: answers the network already gave stand as given. Withdrawing twice is refused. `withdrawn_by` records who took it back: the house (the default), or the platform on its review of a contested answer (`POST /v1/watchtower/contributions/{id}/withdraw`), which only the platform's own rail may say. Emits `fraud_network.contribution_withdrawn`.\n\nEffects: modify hospitality.fraud_network_contribution.", "operationId": "apply_hospitality_action_withdraw_fraud_signal", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why it is being withdrawn", "type": "string" }, "withdrawn_by": { "enum": [ "house", "platform" ], "title": "Who is taking it back: `house` (default), or `platform` on its review of a contest — the platform's rail only", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fraud_network_contribution" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.fraud_network_contribution" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Action applied. `modified_objects` and `modified_links` populated when `return_modified: true` was supplied." }, "409": { "description": "Conflict — concurrent modification or unique constraint violation." }, "422": { "description": "Validation error — parameter validation or business-rule violation." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.withdraw_fraud_signal:apply" ] } ], "summary": "Withdraw fraud signal", "tags": [ "fraud_network" ] } }, "/v1/actions/hospitality.action.withdraw_fraud_signal/preview": { "post": { "description": "Scenario preview of `apply_hospitality_action_withdraw_fraud_signal` — runs the action exactly as apply would (validation, handler dispatch, modified-object projection, commit-time cross-link validation) then rolls the transaction back. Returns the `modified_objects` / `modified_links` / `warnings` the apply would have produced without persisting anything or firing any outward effect. Requires the same `actions:hospitality.action.withdraw_fraud_signal:apply` scope as apply. No `Idempotency-Key`.", "operationId": "preview_hospitality_action_withdraw_fraud_signal", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why it is being withdrawn", "type": "string" }, "withdrawn_by": { "enum": [ "house", "platform" ], "title": "Who is taking it back: `house` (default), or `platform` on its review of a contest — the platform's rail only", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fraud_network_contribution" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil action engine. `correlation_id` ties every event emitted by this invocation; `modified_objects` and `modified_links` project the events the handler emitted (per the action's declared effects); `warnings` carries any non-blocking soft-validator observations.", "properties": { "correlation_id": { "description": "Per-invocation correlation id; matches `events.correlation_id` for every event this action appended.", "format": "uuid", "type": "string" }, "modified_links": { "description": "Links established or removed by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "from_id": { "format": "uuid", "type": "string" }, "from_type": { "type": "string" }, "kind": { "enum": [ "linked", "unlinked", "properties_updated", "end_dated" ] }, "link_type": { "type": "string" }, "to_id": { "format": "uuid", "type": "string" }, "to_type": { "type": "string" } }, "required": [ "link_type", "from_type", "from_id", "to_type", "to_id", "kind" ], "type": "object" }, "type": "array" }, "modified_objects": { "description": "Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request `return_modified`.", "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "modified" ] }, "object_type": { "enum": [ "hospitality.fraud_network_contribution" ] } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "warnings": { "description": "Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.", "items": { "properties": { "message": { "description": "Human-readable summary, suitable for logging or operator-UI surfacing.", "type": "string" }, "object_type": { "description": "Object type the warning was raised against.", "type": "string" }, "property": { "description": "Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.", "type": "string" }, "rule": { "description": "Stable kebab-case rule identifier (e.g. `comp-authority-over-limit`).", "type": "string" } }, "required": [ "rule", "object_type", "message" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "modified_objects", "modified_links" ], "title": "ApplyActionResponse", "type": "object" } } }, "description": "Preview computed and rolled back. `modified_objects` and `modified_links` carry the effect set the apply would produce; `preview` is always `true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — uncommitted live data.", "schema": { "const": "no-store", "type": "string" } } } }, "409": { "description": "Conflict — concurrent modification or unique constraint violation the apply would hit." }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "Preview Withdraw fraud signal (dry-run)", "tags": [ "fraud_network" ] } }, "/v1/actions/hospitality.action.withdraw_fraud_signal/validate": { "post": { "description": "Dry-run of `apply_hospitality_action_withdraw_fraud_signal`'s parameter checks. No side effects, no idempotency reservation, no handler dispatch — just the schema pass plus action-level shape (target presence, target type, unknown-parameter rejection). `return_modified` is meaningless here and ignored.", "operationId": "validate_hospitality_action_withdraw_fraud_signal", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why it is being withdrawn", "type": "string" }, "withdrawn_by": { "enum": [ "house", "platform" ], "title": "Who is taking it back: `house` (default), or `platform` on its review of a contest — the platform's rail only", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fraud_network_contribution" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "action": { "type": "string" }, "errors": { "description": "Action-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "action", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter so a UI can render the action's full surface." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Withdraw fraud signal (dry-run)", "tags": [ "fraud_network" ] } }, "/v1/actions/hospitality.action.withdraw_fraud_signal/whatif": { "post": { "description": "What-if projection of `apply_hospitality_action_withdraw_fraud_signal` — previews the action (execute-and-roll-back) and folds its would-be events into rollup deltas, returning the contribution an apply would make to the `daily_rooms` fact (ADR / RevPAR / TRevPAR / Occupancy inputs) without persisting anything. Requires the same `actions:hospitality.action.withdraw_fraud_signal:apply` scope as apply. An action that emits no rooms-fact events yields an empty `daily_rooms`.", "operationId": "whatif_hospitality_action_withdraw_fraud_signal", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Apply against an open branch's overlay view instead of the canonical (main) plane. The action's writes land in the branch's copy-on-first-write overlay, its events in the branch's own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (`POST /v1/branches` forks one).", "format": "uuid", "type": "string" }, "params": { "additionalProperties": false, "properties": { "reason": { "title": "Why it is being withdrawn", "type": "string" }, "withdrawn_by": { "enum": [ "house", "platform" ], "title": "Who is taking it back: `house` (default), or `platform` on its review of a contest — the platform's rail only", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "return_modified": { "default": false, "description": "When true, the response carries `modified_objects` and `modified_links` projections — the engine reads the event log inside the same transaction so the projection observes the handler's own writes.", "type": "boolean" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fraud_network_contribution" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "daily_rooms": { "description": "Per (property, business_date) additive contribution to the rooms rollup.", "items": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "description": "ISO 4217, when the fold observed one.", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "rooms_revenue_net_delta": { "description": "Decimal, net rooms revenue delta.", "type": "string" }, "rooms_sold_delta": { "format": "int64", "type": "integer" }, "total_revenue_net_delta": { "description": "Decimal, net total revenue delta.", "type": "string" } }, "required": [ "property_id", "business_date", "rooms_sold_delta", "rooms_revenue_net_delta", "total_revenue_net_delta" ], "type": "object" }, "type": "array" } }, "required": [ "daily_rooms" ], "type": "object" } } }, "description": "Rollup deltas the action would contribute, computed and rolled back.", "headers": { "Cache-Control": { "description": "Always `no-store` — derived, uncommitted data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — the apply would be rejected." } }, "summary": "What-if Withdraw fraud signal (rollup delta)", "tags": [ "fraud_network" ] } }, "/v1/agent-authoring/pick-list/{registry_entry_id}": { "get": { "description": "What an author may actually build this agent out of: every object type, action, function and metric the entry is allowed to reach, intersected down twice — once against the entry's own declared maxima (`declared_action_scopes`, `declared_function_scopes`, `declared_data_classes`) and once against the calling author's clearances. A type the author cannot read is absent rather than listed-and-refused, so the pick-list never advertises a capability its holder would be denied at invocation. The entry itself is loaded under the caller's authority, so a marking they cannot read is a `404` like any other redacted read.", "operationId": "get_agent_authoring_pick_list", "parameters": [ { "description": "The `agent_registry_entry` being authored against.", "in": "path", "name": "registry_entry_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAuthoringPickList" } } }, "description": "The intersected catalogue." }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "The composition catalogue for a registry entry", "tags": [ "agents" ] } }, "/v1/agent-traces": { "get": { "description": "Newest-activity-first session summaries, optionally filtered to one agent. Requires `traces:read`.", "operationId": "list_agent_trace_sessions", "parameters": [ { "in": "query", "name": "agent_name", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "agent_name": { "type": "string" }, "last_at": { "format": "date-time", "type": "string" }, "last_event": { "type": "string" }, "session_id": { "type": "string" }, "span_count": { "type": "integer" }, "started_at": { "format": "date-time", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Session summaries" } }, "summary": "List stored agent-run trace sessions", "tags": [ "agent-traces" ] } }, "/v1/agent-traces/{session_id}": { "get": { "description": "The session's enveloped trace rows in emission order plus attached assessments. Requires `traces:read`.", "operationId": "get_agent_trace_session", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "agent_name": { "type": "string" }, "assessments": { "items": { "type": "object" }, "type": "array" }, "session_id": { "type": "string" }, "spans": { "items": { "properties": { "row": { "type": "object" }, "seq": { "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "Spans + assessments" }, "404": { "description": "No trace stored for the session" } }, "summary": "Replay one stored agent-run trace", "tags": [ "agent-traces" ] } }, "/v1/agent-traces/{session_id}/assessments": { "post": { "description": "Typed verdict on a session or one span of it: `feedback` (judgement of what happened) or `expectation` (what should have happened). Requires `traces:write`.", "operationId": "attach_agent_trace_assessment", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "kind": { "enum": [ "feedback", "expectation" ], "type": "string" }, "span_seq": { "description": "Attach to one span instead of the whole session.", "type": "integer" }, "value": {} }, "required": [ "kind", "value" ], "type": "object" } } }, "required": true }, "responses": { "201": { "description": "Assessment attached" }, "404": { "description": "No trace stored for the session" } }, "summary": "Attach an assessment to a stored trace", "tags": [ "agent-traces" ] } }, "/v1/agent-traces/{session_id}/promote": { "post": { "description": "Mints an `agent_eval_case` from the trace (design D8): the task comes from the `run.started` row, the graders from observed behaviour (`run.completes` plus `run.proposes` per action routed through propose_action). Requires `traces:write`.", "operationId": "promote_agent_trace", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "case_name": { "description": "Suite-unique case name; defaults to `{agent}_{session prefix}`.", "type": "string" } }, "type": "object" } } }, "required": false }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "agent_eval_case_id": { "format": "uuid", "type": "string" }, "case_name": { "type": "string" }, "graders": { "items": { "type": "object" }, "type": "array" }, "source_session_id": { "type": "string" } }, "type": "object" } } }, "description": "Eval case minted" }, "404": { "description": "No trace stored for the session" }, "409": { "description": "Trace lacks a run.started row" } }, "summary": "Promote a stored trace to an agent eval case", "tags": [ "agent-traces" ] } }, "/v1/agent-traces/{session_id}/spans": { "post": { "description": "Append a batch of enveloped trace rows exactly as the runtime emitted them (`ts`, `session_id`, `gen_ai.agent.name`, typed event payload). Idempotent per `(session, seq)` — re-posting a batch no-ops, so blind retries are safe. Requires `traces:write`.", "operationId": "ingest_agent_trace_spans", "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "rows": { "description": "Enveloped trace rows, verbatim.", "items": { "type": "object" }, "type": "array" }, "start_seq": { "default": 0, "description": "Sequence number of rows[0]; the uploader keeps incremental batches contiguous.", "minimum": 0, "type": "integer" } }, "required": [ "rows" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "inserted": { "type": "integer" }, "next_seq": { "type": "integer" }, "session_id": { "type": "string" } }, "type": "object" } } }, "description": "Batch absorbed" } }, "summary": "Ingest agent-run trace spans", "tags": [ "agent-traces" ] } }, "/v1/analytics/booking-pace": { "get": { "description": "The booking curve for one (property, stay date, segment): every daily on-the-books snapshot the booking-pace sweep has recorded, ordered by snapshot date (analytics decision doc 04 §5a / §5f). \n\n**A typed fact query, not a metric.** A curve is ordered rows with self-join deltas, which the conformed-metric grammar cannot express; this is the first member of the `/v1/analytics/*` fact-query family. \n\n**OTB semantics.** Each row freezes the on-the-books state at the property-local cutoff (default 23:59): reservation-nights of reservations in `confirmed` / `modified` / `in_house`; `held`, `cancelled`, `no_show`, and `checked_out` are excluded. Rows exist for every stay date in the lookahead horizon — zero-OTB dates included — and are immutable once written: a later cancellation shows up as negative pickup in later rows, never as a mutation. \n\n**Pickup horizons.** `rooms_picked_up_1d` / `revenue_picked_up_1d` are stored; longer horizons (`horizons=7,14,30`) are computed read-time by diffing against the row that many snapshot days earlier in the same curve. \n\nLive data: always `Cache-Control: no-store`.", "operationId": "booking_pace", "parameters": [ { "description": "Property whose curve to read.", "in": "query", "name": "property_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "The stay (occupancy) date whose booking curve to read, `YYYY-MM-DD`. Named for the industry's pace vocabulary; a multi-night stay contributes a night to each stay date it covers.", "in": "query", "name": "arrival_date", "required": true, "schema": { "format": "date", "type": "string" } }, { "description": "`total` (default) | `transient` | `group` | `contract`. The sweep writes `total` for every property plus one curve per segment the property actually sells, discovered from the horizon rather than from the declared vocabulary — so a segment a house never sells returns an empty curve, and `total` is by construction the sum of the segments plus whatever is unsegmented.", "in": "query", "name": "segment", "required": false, "schema": { "default": "total", "enum": [ "total", "transient", "group", "contract" ], "type": "string" } }, { "description": "Comma-separated pickup horizons in days (e.g. `7,14,30`; at most 5, each 1–365). Adds a `pickup` array per row, diffed against the row that many snapshot days earlier; a horizon with no prior row yields nulls.", "in": "query", "name": "horizons", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingPaceResponse" } } }, "description": "The booking curve, ordered by `snapshot_date_local` ascending. An unknown property or a curve with no snapshots yet is an empty `rows` array, not a 404.", "headers": { "Cache-Control": { "description": "Always `no-store` — live data.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Token lacks the `analytics:read` scope." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Malformed `arrival_date`, unknown `segment`, or out-of-range `horizons`." } }, "security": [ { "aerandil_oauth": [ "analytics:read" ] } ], "summary": "Read a booking curve (pace / pickup)", "tags": [ "analytics" ] } }, "/v1/analytics/booking-pace/capture": { "post": { "description": "Take the current business day's booking-pace snapshot for one property now, instead of waiting for the nightly property-local cutoff sweep. \n\n**Which business day.** Inside the post-cutoff grace window this captures the just-ended business day — the exact unit the sweep would take, just sooner. Past the grace window it captures the in-progress business day early; `captured_at` on the fact rows records the true moment, so an early curve point is honest about when it was frozen. Lapsed windows are never backfilled — live tables cannot reconstruct end-of-day state after the fact. \n\n**`as_of`.** A house whose business time is not the clock's — a replayed or simulated booking log — names the business day it is closing instead. It is admitted only while no reservation of the property was booked or cancelled on a later day, which is exactly when the live tables still are that day's end-of-day book; a live house, which books every day, cannot use it to backfill. \n\n**At most one snapshot per business day.** Snapshot rows are immutable once written: a repeat capture, or the nightly sweep arriving later, is a no-op (`200` with `captured: false`). \n\nAccepts an `Idempotency-Key` header for retry-safe automation, though the once-per-business-day claim already makes the operation naturally idempotent.", "operationId": "capture_booking_pace", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingPaceCaptureRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingPaceCaptureResponse" } } }, "description": "That business day's snapshot already existed (`captured: false`); nothing was written." }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingPaceCaptureResponse" } } }, "description": "Snapshot captured — one row per stay date in the lookahead horizon was written." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Token lacks the `analytics:write` scope." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No such property in this tenant." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`as_of` names a day the property cannot give: in the future, or one its book has moved past (`booking_pace_as_of_refused`)." } }, "security": [ { "aerandil_oauth": [ "analytics:write" ] } ], "summary": "Capture a booking-pace snapshot on demand", "tags": [ "analytics" ] } }, "/v1/analytics/switchover-shadow": { "get": { "description": "One connector's source PMS against Aerandil during the shadow run before cutover: per stream, what the loader has loaded, has still to load, rejected or deferred (and the newest rejects with their reasons); for the business date and the nine days after it, arrivals and departures on both sides (and in-house guests for the day); and per folio, the vendor's status, dates, room and balance (charges less payments plus settled refunds, over every staged row naming the reservation, loaded or not) against the reservation's own (its stays' folios and rooms). Every disagreement is a named discrepancy: `not_loaded`, `status_mismatch`, `dates_mismatch`, `balance_mismatch` and `room_mismatch` block a cutover; `aerandil_only` (a booking at a house this connector feeds that the source never sent) is advisory. Only discrepant folios are listed; `summary` counts them all. `ready_to_cut_over` is no blocking discrepancy on an `active` connector. \n\n**Mapping-driven.** The vendor side is read through the connector's own mapping files — the pointers they declare, the loader's coercion, the lifecycle their update variants dispatch — so it sees what the loader sees. `blind_spots` names, per provider, what the connector deliberately does not carry. \n\nLive data: always `Cache-Control: no-store`.", "operationId": "switchover_shadow", "parameters": [ { "description": "The connector object's id.", "in": "query", "name": "connector_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "The business date, `YYYY-MM-DD`. Defaults to today in the property's timezone when the connector feeds one property, else today in UTC.", "in": "query", "name": "business_date", "required": false, "schema": { "format": "date", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "as_of": { "description": "When the comparison was read.", "format": "date-time", "type": "string" }, "blind_spots": { "description": "What this provider's feed cannot show, so the comparison cannot either (company accounts, pre-arrival deposits, refund legs, …) — the checks the house makes by hand.", "items": { "type": "string" }, "type": "array" }, "business_date": { "format": "date", "type": "string" }, "connector_business_id": { "description": "The connector's business id (`CN-…`): the `source` of its staged rows and the prefix of every external_ref it lands.", "type": "string" }, "connector_id": { "format": "uuid", "type": "string" }, "cut_over_at": { "description": "When the house cut over from this source; absent while shadowing.", "format": "date-time", "type": [ "string", "null" ] }, "day": { "description": "The business date's movement counts, computed identically both sides: arrivals and departures are non-cancelled reservations arriving / departing that day; in_house is reservations in house.", "properties": { "agree": { "description": "Every count matches across the two sides.", "type": "boolean" }, "arrivals": { "properties": { "aerandil": { "type": "integer" }, "source": { "type": "integer" } }, "required": [ "source", "aerandil" ], "type": "object" }, "departures": { "properties": { "aerandil": { "type": "integer" }, "source": { "type": "integer" } }, "required": [ "source", "aerandil" ], "type": "object" }, "in_house": { "properties": { "aerandil": { "type": "integer" }, "source": { "type": "integer" } }, "required": [ "source", "aerandil" ], "type": "object" } }, "required": [ "arrivals", "departures", "in_house", "agree" ], "type": "object" }, "discrepancies": { "description": "Every disagreement, named. Blocking: not_loaded (a pending, rejected or deferred row — detail carries the load error), status_mismatch, dates_mismatch, balance_mismatch, room_mismatch (an in-house reservation whose source room differs from its Aerandil stay's). Advisory: aerandil_only (a non-cancelled reservation at a property this connector feeds that the source never sent).", "items": { "properties": { "detail": { "type": "string" }, "external_id": { "type": [ "string", "null" ] }, "kind": { "enum": [ "not_loaded", "status_mismatch", "dates_mismatch", "balance_mismatch", "room_mismatch", "aerandil_only" ], "type": "string" }, "reservation_id": { "format": "uuid", "type": [ "string", "null" ] }, "severity": { "enum": [ "blocking", "advisory" ], "type": "string" }, "stream": { "type": [ "string", "null" ] } }, "required": [ "kind", "severity", "detail" ], "type": "object" }, "type": "array" }, "folios": { "description": "Only the folios with a discrepancy — one per reservation the source sent; `summary` carries the counts over all of them. The source balance is its charges less its payments over every staged row referencing the reservation, loaded or not; the Aerandil balance is the sum of the reservation's stays' folio balances.", "items": { "properties": { "aerandil": { "properties": { "arrival_date": { "format": "date", "type": [ "string", "null" ] }, "balance": { "format": "decimal", "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "departure_date": { "format": "date", "type": [ "string", "null" ] }, "room": { "description": "The room code of the reservation's stay, when one is assigned.", "type": [ "string", "null" ] }, "rows_loaded": { "properties": { "charges": { "type": "integer" }, "payments": { "type": "integer" }, "refunds": { "type": "integer" } }, "required": [ "charges", "payments", "refunds" ], "type": "object" }, "status": { "description": "The reservation's status; null when it never loaded.", "type": [ "string", "null" ] } }, "required": [ "status", "arrival_date", "departure_date", "rows_loaded" ], "type": "object" }, "confirmation_number": { "type": [ "string", "null" ] }, "discrepancies": { "items": { "enum": [ "not_loaded", "status_mismatch", "dates_mismatch", "balance_mismatch", "room_mismatch", "aerandil_only" ], "type": "string" }, "type": "array" }, "external_id": { "description": "The reservation's id in the source PMS.", "type": "string" }, "reservation_id": { "description": "The Aerandil reservation; null when it never loaded.", "format": "uuid", "type": [ "string", "null" ] }, "source": { "properties": { "arrival_date": { "format": "date", "type": [ "string", "null" ] }, "balance": { "format": "decimal", "type": "string" }, "charges": { "format": "decimal", "type": "string" }, "currency": { "type": [ "string", "null" ] }, "departure_date": { "format": "date", "type": [ "string", "null" ] }, "payments": { "format": "decimal", "type": "string" }, "refunds": { "format": "decimal", "type": "string" }, "room": { "description": "The room code the source assigns, when its feed carries one.", "type": [ "string", "null" ] }, "rows": { "properties": { "charges": { "type": "integer" }, "payments": { "type": "integer" }, "refunds": { "type": "integer" } }, "required": [ "charges", "payments", "refunds" ], "type": "object" }, "status": { "description": "The lifecycle the source row reads as through the mapping: confirmed, in_house, checked_out, cancelled or no_show.", "type": [ "string", "null" ] }, "variant": { "description": "The mapping's update variant the row matched (its own name), or null for a create-only row.", "type": [ "string", "null" ] } }, "required": [ "status", "arrival_date", "departure_date", "charges", "payments", "refunds", "balance", "rows" ], "type": "object" } }, "required": [ "external_id", "source", "aerandil", "discrepancies" ], "type": "object" }, "type": "array" }, "horizon": { "description": "The business date and the nine days after it — the go-live check for overbookings in the next days: arrivals and departures both sides, per date, ascending.", "items": { "properties": { "agree": { "type": "boolean" }, "arrivals": { "properties": { "aerandil": { "type": "integer" }, "source": { "type": "integer" } }, "required": [ "source", "aerandil" ], "type": "object" }, "date": { "format": "date", "type": "string" }, "departures": { "properties": { "aerandil": { "type": "integer" }, "source": { "type": "integer" } }, "required": [ "source", "aerandil" ], "type": "object" } }, "required": [ "date", "arrivals", "departures", "agree" ], "type": "object" }, "type": "array" }, "provider": { "type": "string" }, "ready_to_cut_over": { "description": "No blocking discrepancy and the connector is active.", "type": "boolean" }, "rejects": { "description": "The rejected rows, newest first, at most 200.", "items": { "properties": { "error": { "type": [ "string", "null" ] }, "external_id": { "type": "string" }, "mapping_ref": { "type": [ "string", "null" ] }, "since": { "description": "When the row was last tried and refused.", "format": "date-time", "type": "string" }, "stream": { "type": "string" } }, "required": [ "stream", "external_id", "error", "mapping_ref", "since" ], "type": "object" }, "maxItems": 200, "type": "array" }, "status": { "description": "The connector's lifecycle status.", "enum": [ "active", "paused", "retired" ], "type": "string" }, "streams": { "description": "Per staged stream, its rows by load outcome. A staged row with no load outcome yet is pending.", "items": { "properties": { "deferred": { "type": "integer" }, "loaded": { "type": "integer" }, "mapping_ref": { "description": "The connector's mapping for the stream (`name@version`); null when it carries none.", "type": [ "string", "null" ] }, "pending": { "type": "integer" }, "rejected": { "type": "integer" }, "stream": { "type": "string" } }, "required": [ "stream", "mapping_ref", "loaded", "pending", "rejected", "deferred" ], "type": "object" }, "type": "array" }, "summary": { "properties": { "advisory": { "type": "integer" }, "blocking": { "type": "integer" }, "folios_agreeing": { "type": "integer" }, "folios_compared": { "type": "integer" } }, "required": [ "folios_compared", "folios_agreeing", "blocking", "advisory" ], "type": "object" } }, "required": [ "connector_id", "connector_business_id", "provider", "status", "business_date", "as_of", "streams", "rejects", "day", "horizon", "folios", "discrepancies", "summary", "blind_spots", "ready_to_cut_over" ], "type": "object" } } }, "description": "The shadow comparison.", "headers": { "Cache-Control": { "description": "Always `no-store` — live data.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Token lacks the `analytics:read` scope, or is a desk session bound to one property (a connector spans the houses it feeds)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No such connector." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The connector's mappings do not form a runnable pipeline (`connector_pipeline_invalid`) — the worker pauses such a connector; repoint it first." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Malformed `business_date`." } }, "security": [ { "aerandil_oauth": [ "analytics:read" ] } ], "summary": "Read a PMS switchover's shadow comparison", "tags": [ "analytics" ] } }, "/v1/analytics/trial-balance": { "get": { "description": "The night audit's trial balance for one property and one business date, folded from the ledgers' entries (`folio.balance_moved.recorded`, and `ledger.balance_moved.recorded` for the ledgers no folio holds): the guest, deposit, A/R, package and inter-hotel ledgers with their opening, the day's debits and credits, and their closing; the day's revenue by USALI department, tax, gratuities, payments by method, internal transfers and drift corrections; and the proof — the folio ledgers' (guest, deposit, A/R) closing (`ledger_total`) against the folios' own stored balances at that close (`stored_total`: read live, brought back to the day's close by the entries dated after it), `in_balance` when `difference` is zero. \n\n**Dated by posting.** An entry belongs to the hotel date it was posted on — the business date the property had open, so a posting after midnight and before the close lands on the day still open (the night audit's room nights to the day it closes) — and a closed day's figures never move; a correction lands on the day it is made. \n\n**Deterministic.** Everything but `projection` and the totals' `stored_total` / `difference` / `in_balance` is a pure function of the event log: the same date reads byte-identically after any re-fold. Those three compare the fold with the folios as they stand at read time, so the rollup never stores them. `projection` reports the fold's freshness (`lag_events` > 0 means entries are still to be folded, and shows as a `difference`). \n\nLive data: always `Cache-Control: no-store`.", "operationId": "trial_balance", "parameters": [ { "description": "Property whose ledgers to read.", "in": "query", "name": "property_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "The business date, `YYYY-MM-DD`.", "in": "query", "name": "business_date", "required": true, "schema": { "format": "date", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "business_date": { "format": "date", "type": "string" }, "ledgers": { "description": "guest, deposit, ar, package, inter_hotel — in that order, per currency. The package ledger is allowance set aside from the room rate and not yet consumed or cleared (a credit balance); the inter-hotel ledger is what the group's other houses owe this one.", "items": { "properties": { "closing": { "format": "decimal", "type": "string" }, "credits": { "format": "decimal", "type": "string" }, "currency": { "type": "string" }, "debits": { "format": "decimal", "type": "string" }, "entries": { "type": "integer" }, "ledger": { "enum": [ "guest", "deposit", "ar", "package", "inter_hotel" ], "type": "string" }, "opening": { "format": "decimal", "type": "string" } }, "required": [ "ledger", "currency", "opening", "debits", "credits", "closing", "entries" ], "type": "object" }, "type": "array" }, "lines": { "description": "The day's movements by section (revenue, tax, non_revenue, payment, transfer, opening, adjustment) and line; net = debits − credits from the folios' side.", "items": { "properties": { "credits": { "format": "decimal", "type": "string" }, "currency": { "type": "string" }, "debits": { "format": "decimal", "type": "string" }, "entries": { "type": "integer" }, "line": { "type": "string" }, "net": { "format": "decimal", "type": "string" }, "section": { "type": "string" } }, "required": [ "section", "line", "currency", "debits", "credits", "net", "entries" ], "type": "object" }, "type": "array" }, "payouts": { "description": "The payouts in the close (2026-10-18): the day's card payments (received in the house's calendar day, settled or since refunded) with the day their money became available to pay out — `pending` until the payout carrying it has reconciled — and the payouts that arrived (`arrival_date`) or failed that day, with their reconciliation counts. A fold over the ledger's rows, byte-identical on re-read.", "properties": { "business_date": { "format": "date", "type": "string" }, "by_method": { "items": { "properties": { "count": { "type": "integer" }, "currency": { "type": "string" }, "method": { "type": "string" }, "total": { "format": "decimal", "type": "string" } }, "type": "object" }, "type": "array" }, "payments": { "items": { "properties": { "amount": { "format": "decimal", "type": [ "string", "null" ] }, "available_on": { "description": "YYYY-MM-DD, or `pending`.", "type": "string" }, "currency": { "type": [ "string", "null" ] }, "method": { "type": "string" }, "payment_id": { "format": "uuid", "type": "string" }, "payout_reference": { "type": [ "string", "null" ] }, "received_at": { "format": "date-time", "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" }, "payouts": { "items": { "properties": { "amount": { "format": "decimal", "type": [ "string", "null" ] }, "arrival_date": { "format": "date", "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "failure_code": { "type": [ "string", "null" ] }, "failure_message": { "type": [ "string", "null" ] }, "fees_total": { "format": "decimal", "type": [ "string", "null" ] }, "line_count": { "type": [ "integer", "null" ] }, "matched_count": { "type": [ "integer", "null" ] }, "payout_id": { "format": "uuid", "type": "string" }, "psp_reference": { "type": [ "string", "null" ] }, "reconciliation_status": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "unmatched_amount": { "format": "decimal", "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" }, "projection": { "description": "Freshness of the fold — not part of the statement.", "properties": { "folded_through_seq": { "type": "integer" }, "lag_events": { "type": "integer" }, "last_folded_at": { "format": "date-time", "type": [ "string", "null" ] }, "name": { "type": "string" } }, "type": "object" }, "property_id": { "format": "uuid", "type": "string" }, "totals": { "items": { "properties": { "balance_brought_forward": { "format": "decimal", "type": "string" }, "balance_carried_forward": { "format": "decimal", "type": "string" }, "currency": { "type": "string" }, "difference": { "description": "stored_total − ledger_total: drift between the folios' cached balances and their entries (or entries not yet folded — see projection.lag_events).", "format": "decimal", "type": "string" }, "in_balance": { "description": "difference is zero (and brought forward plus the day's transactions equals the ledgers' closing).", "type": "boolean" }, "ledger_balance": { "format": "decimal", "type": "string" }, "ledger_total": { "description": "The folio ledgers' (guest, deposit, ar) closing — what the folios should hold at this day's close.", "format": "decimal", "type": "string" }, "stored_total": { "description": "The folios' stored balances, read live and brought back to this day's close by the folio-ledger entries dated after it.", "format": "decimal", "type": "string" }, "transactions_today": { "format": "decimal", "type": "string" } }, "required": [ "currency", "balance_brought_forward", "transactions_today", "balance_carried_forward", "ledger_balance", "ledger_total", "stored_total", "difference", "in_balance" ], "type": "object" }, "type": "array" } }, "required": [ "property_id", "business_date", "ledgers", "lines", "totals" ], "type": "object" } } }, "description": "The trial balance. A property or day with no entries is an empty statement, not a 404.", "headers": { "Cache-Control": { "description": "Always `no-store` — live data.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Token lacks the `analytics:read` scope." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Malformed `business_date`." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The `trial_balance` projection has not completed a healthy tick (`projection_unavailable`); retry after `Retry-After`." } }, "summary": "Read a trial balance", "tags": [ "analytics" ] } }, "/v1/attachments": { "post": { "description": "Open a `pending` `stored_object` reference against a host object (`person` / `reservation` / `property`) and mint a short-lived presigned S3 `PUT` the client uploads the bytes to directly. The row starts `pending`; the bytes are not the source of truth until `POST /v1/attachments/{id}/finalize` HEAD-verifies them. \n\n**Scope: `objects:write`.** \n\n**Requires `AERANDIL_OBJECT_STORE_ENABLED`** — returns `501` when object storage is not configured for the cell. \n\n**Idempotent via `Idempotency-Key`.** A replay returns the original envelope with `idempotent_replay: true` added, rather than opening a second reference.", "operationId": "initiate_attachment_upload", "parameters": [ { "description": "Opaque idempotency token (Stripe-shape). Repeated POSTs with the same key replay the original response within the cache TTL rather than creating a duplicate object.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "content_category": { "description": "Optional caller-assigned classification (e.g. `id_document`, `invoice`).", "type": "string" }, "content_type": { "description": "Declared MIME type of the upload; HEAD-verified against the actual bytes at finalize.", "type": "string" }, "filename": { "description": "Optional original filename, preserved for the download disposition.", "type": "string" }, "host_id": { "description": "Id of the host object.", "format": "uuid", "type": "string" }, "host_kind": { "description": "The object type the attachment hangs off.", "enum": [ "person", "reservation", "property" ], "type": "string" }, "max_bytes": { "description": "Optional caller ceiling on the upload size, clamped to the bucket max.", "format": "int64", "type": "integer" } }, "required": [ "host_kind", "host_id", "content_type" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "id": { "format": "uuid", "type": "string" }, "idempotent_replay": { "description": "Present and `true` only on an idempotent replay.", "type": "boolean" }, "max_bytes": { "format": "int64", "type": "integer" }, "status": { "const": "pending" }, "upload": { "properties": { "expires_at": { "format": "date-time", "type": "string" }, "headers": { "description": "Headers the client MUST echo verbatim on the presigned PUT.", "items": { "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ], "type": "object" }, "type": "array" }, "method": { "type": "string" }, "url": { "type": "string" } }, "required": [ "url", "method", "headers", "expires_at" ], "type": "object" } }, "required": [ "id", "status", "max_bytes", "upload" ], "type": "object" } } }, "description": "Pending reference opened; the body carries the presigned upload. An idempotent replay adds `idempotent_replay: true`.", "headers": { "Cache-Control": { "description": "Always `no-store` — live data is never cacheable.", "schema": { "const": "no-store", "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing the `objects:write` scope." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid body — malformed `host_kind`, `host_id`, or `content_type`." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Object storage not enabled (`AERANDIL_OBJECT_STORE_ENABLED` unset)." } }, "security": [ { "aerandil_oauth": [ "objects:write" ] } ], "summary": "Open a pending attachment + mint a presigned upload", "tags": [ "stored_objects" ] } }, "/v1/attachments/{id}": { "delete": { "description": "Soft-delete the `stored_object` reference via the typed `delete_stored_object` action. The row is tombstoned; the underlying bytes are reaped asynchronously by an object- storage lifecycle rule, not by this call. \n\n**Scope: `objects:write`.** \n\n**Requires `AERANDIL_OBJECT_STORE_ENABLED`** — `501` otherwise.", "operationId": "delete_attachment", "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Optional soft-delete justification recorded on the `stored_object.deleted` event.", "in": "query", "name": "reason", "required": false, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Soft-deleted; bytes reaped by a storage lifecycle rule." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing the `objects:write` scope." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No such attachment for this tenant." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Object storage not enabled (`AERANDIL_OBJECT_STORE_ENABLED` unset)." } }, "security": [ { "aerandil_oauth": [ "objects:write" ] } ], "summary": "Soft-delete an attachment reference", "tags": [ "stored_objects" ] } }, "/v1/attachments/{id}/download": { "get": { "description": "Mint a short-lived presigned S3 `GET` for an `available` attachment. The bytes stream directly from object storage; the API only signs the URL. \n\n**Scope: `objects:read`.** \n\n**Requires `AERANDIL_OBJECT_STORE_ENABLED`** — `501` otherwise.", "operationId": "download_attachment", "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "expires_at": { "format": "date-time", "type": "string" }, "method": { "type": "string" }, "url": { "type": "string" } }, "required": [ "url", "method", "expires_at" ], "type": "object" } } }, "description": "A presigned download URL and its expiry.", "headers": { "Cache-Control": { "description": "Always `no-store` — live data is never cacheable.", "schema": { "const": "no-store", "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing the `objects:read` scope." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No such attachment for this tenant." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`attachment_not_available` — only an `available` attachment can be downloaded." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Object storage not enabled (`AERANDIL_OBJECT_STORE_ENABLED` unset)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Mint a presigned download for an available attachment", "tags": [ "stored_objects" ] } }, "/v1/attachments/{id}/finalize": { "post": { "description": "Confirm a pending attachment: the server issues a HEAD against the uploaded object and reconciles the actual `byte_size` / `checksum` / `content_type` / `etag` against the declared intent, then flips the `stored_object` to `available`. This is where object storage becomes the source of truth — the row's `available` facts are the ones the bytes actually have, not the ones the client claimed. \n\n**Scope: `objects:write`.** \n\n**Requires `AERANDIL_OBJECT_STORE_ENABLED`** — `501` otherwise.", "operationId": "finalize_attachment", "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The finalized `stored_object` — `status` `available`, with the byte_size / checksum / content_type / etag the HEAD verified.", "type": "object" } } }, "description": "Attachment finalized. The body is the `stored_object` resource carrying the HEAD-verified `available` facts.", "headers": { "Cache-Control": { "description": "Always `no-store` — live data is never cacheable.", "schema": { "const": "no-store", "type": "string" } }, "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing the `objects:write` scope." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No such attachment for this tenant." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`upload_verification_failed` — the uploaded bytes don't match the declared intent." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Object storage not enabled (`AERANDIL_OBJECT_STORE_ENABLED` unset)." } }, "security": [ { "aerandil_oauth": [ "objects:write" ] } ], "summary": "Finalize an upload (HEAD-verify the bytes)", "tags": [ "stored_objects" ] } }, "/v1/branches": { "get": { "description": "Every branch under the caller's tenant, newest first — open and merged both (a merged row is the durable merge record). Requires `objects:read`.", "operationId": "list_branches", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "forked_at_seq": { "description": "The caller-tenant's event-stream head `seq` at fork (fork-from-head only).", "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_write_at": { "format": "date-time", "type": "string" }, "merge_correlation_id": { "description": "Present on a merged branch: the correlation id stamped on the `branch.merged` event and shared by every replayed main-log write, tying the merge record to the replayed events.", "format": "uuid", "type": "string" }, "merged_at": { "format": "date-time", "type": "string" }, "name": { "type": "string" }, "status": { "enum": [ "open", "merged" ], "type": "string" } }, "required": [ "id", "name", "status", "forked_at_seq", "created_at" ], "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "Branches for the tenant.", "headers": { "Cache-Control": { "description": "Always `no-store` — live data.", "schema": { "const": "no-store", "type": "string" } } } } }, "summary": "List branches", "tags": [ "branches" ] }, "post": { "description": "Fork a new open branch at the head of the caller-tenant's event stream. Sibling delta tables carry copy-on-first-write overlay rows; the base plane pays zero tax. At most one open branch per name per tenant — a merged or discarded branch frees its name. Accepts `Idempotency-Key`. Requires `objects:write`.", "operationId": "create_branch", "parameters": [ { "description": "Opaque idempotency token (Stripe-shape). Repeated POSTs with the same key replay the original response within the cache TTL rather than creating a duplicate object.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "name": { "description": "Unique among the tenant's open branches.", "maxLength": 200, "minLength": 1, "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "forked_at_seq": { "description": "The caller-tenant's event-stream head `seq` at fork (fork-from-head only).", "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_write_at": { "format": "date-time", "type": "string" }, "merge_correlation_id": { "description": "Present on a merged branch: the correlation id stamped on the `branch.merged` event and shared by every replayed main-log write, tying the merge record to the replayed events.", "format": "uuid", "type": "string" }, "merged_at": { "format": "date-time", "type": "string" }, "name": { "type": "string" }, "status": { "enum": [ "open", "merged" ], "type": "string" } }, "required": [ "id", "name", "status", "forked_at_seq", "created_at" ], "type": "object" } } }, "description": "Branch forked." }, "409": { "description": "A branch with this name is already open." }, "422": { "description": "Invalid branch name." } }, "summary": "Create (fork) a branch", "tags": [ "branches" ] } }, "/v1/branches/{id}": { "delete": { "description": "Discard an open branch: hard-delete its overlay delta rows and the branch row itself. Branch rows are hypothesis, not history, so nothing survives and the name frees for reuse. A merged branch refuses (409) — its row is the merge record. Requires `objects:write`.", "operationId": "discard_branch", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Discarded." }, "404": { "description": "No such branch under this tenant." }, "409": { "description": "Branch is merged and cannot be discarded." } }, "summary": "Discard a branch", "tags": [ "branches" ] }, "get": { "description": "One branch by id, under the caller's tenant. Requires `objects:read`.", "operationId": "get_branch", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "forked_at_seq": { "description": "The caller-tenant's event-stream head `seq` at fork (fork-from-head only).", "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_write_at": { "format": "date-time", "type": "string" }, "merge_correlation_id": { "description": "Present on a merged branch: the correlation id stamped on the `branch.merged` event and shared by every replayed main-log write, tying the merge record to the replayed events.", "format": "uuid", "type": "string" }, "merged_at": { "format": "date-time", "type": "string" }, "name": { "type": "string" }, "status": { "enum": [ "open", "merged" ], "type": "string" } }, "required": [ "id", "name", "status", "forked_at_seq", "created_at" ], "type": "object" } } }, "description": "The branch." }, "404": { "description": "No such branch under this tenant." } }, "summary": "Get a branch", "tags": [ "branches" ] } }, "/v1/branches/{id}/merge": { "post": { "description": "Merge an open branch into main by **replaying its action journal** through the engine against the current main state — validators and all — in one atomic transaction. A fast-fail staleness check runs first: any copy-on-first-write row whose base has moved (or been deleted) since the fork aborts the merge with a structured conflict (409), never a row-level three-way merge. On success the branch is marked merged (recording the umbrella `merge_correlation_id`), its delta rows are deleted, and a `branch.merged` event lands on the main log. Accepts `Idempotency-Key`. Because the replay may fire any journaled action, this requires the `actions:apply` catch-all scope.", "operationId": "merge_branch", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Opaque idempotency token (Stripe-shape). Repeated POSTs with the same key replay the original response within the cache TTL rather than creating a duplicate object.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "branch_id": { "format": "uuid", "type": "string" }, "merge_correlation_id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "replayed": { "items": { "properties": { "action": { "type": "string" }, "correlation_id": { "format": "uuid", "type": "string" }, "ordinal": { "type": "integer" } }, "required": [ "ordinal", "action", "correlation_id" ], "type": "object" }, "type": "array" }, "warnings": { "items": { "type": "object" }, "type": "array" } }, "required": [ "branch_id", "name", "merge_correlation_id", "replayed" ], "type": "object" } } }, "description": "Merged. `replayed` lists each journal entry's fresh main-log correlation id." }, "404": { "description": "No such branch under this tenant." }, "409": { "description": "Branch is not open, or the staleness check found conflicts against main." } }, "summary": "Merge a branch (merge-by-replay)", "tags": [ "branches" ] } }, "/v1/catalogue/health": { "get": { "description": "Per-tenant read-side aggregations over signals other proposals already write (proposal 0028 §6): consent posture (count of objects with a `consent_scope.revoked_at` tombstone, grouped by type — 0026), duplicate pressure (open `person_merge_candidate` count — 0027), and projection staleness (per `_computed_at` projection: live-row count and oldest refresh timestamp). Not a quality-rules engine; a rollup view.", "operationId": "catalogue_health", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "consent_posture": { "properties": { "revoked_by_type": { "items": { "type": "object" }, "type": "array" }, "total_revoked": { "type": "integer" } }, "required": [ "total_revoked", "revoked_by_type" ], "type": "object" }, "duplicate_pressure": { "properties": { "open_person_merge_candidates": { "type": "integer" } }, "required": [ "open_person_merge_candidates" ], "type": "object" }, "staleness": { "items": { "properties": { "object_type": { "type": "string" }, "oldest_computed_at": { "format": "date-time", "type": [ "string", "null" ] }, "projection": { "type": "string" }, "rows": { "type": "integer" } }, "required": [ "object_type", "projection", "rows" ], "type": "object" }, "type": "array" } }, "required": [ "consent_posture", "duplicate_pressure", "staleness" ], "type": "object" } } }, "description": "The per-tenant catalogue health rollup." } }, "summary": "Catalogue health rollup", "tags": [ "catalogue" ] } }, "/v1/catalogue/lineage/downstream": { "get": { "description": "The inference outputs whose DataLineage names `(asset_type, asset_id)` as a source object — 'what consumes this asset' (proposal 0028 §5). Reads the 0026 `events.lineage` reverse-index, newest inference first.", "operationId": "catalogue_lineage_downstream", "parameters": [ { "description": "Object type of the source asset (ApiName).", "in": "query", "name": "asset_type", "required": true, "schema": { "type": "string" } }, { "description": "Object id of the source asset.", "in": "query", "name": "asset_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Max consumers to return (default 50, capped 200).", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "asset": { "type": "object" }, "downstream": { "items": { "type": "object" }, "type": "array" } }, "required": [ "asset", "downstream" ], "type": "object" } } }, "description": "The inference outputs consuming the asset." }, "400": { "description": "Missing or malformed asset_type / asset_id." } }, "summary": "Downstream lineage: inferences consuming an asset", "tags": [ "catalogue" ] } }, "/v1/catalogue/lineage/upstream": { "get": { "description": "The full DataLineage envelope of one inference output (source objects/events, model, training cohort, and column-level edges), keyed by the inference event's `seq` (proposal 0028 §5).", "operationId": "catalogue_lineage_upstream", "parameters": [ { "description": "The `seq` of the inference.recorded event.", "in": "query", "name": "inference_seq", "required": true, "schema": { "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "inference_seq": { "format": "int64", "type": "integer" }, "upstream": { "type": "object" } }, "required": [ "inference_seq", "upstream" ], "type": "object" } } }, "description": "The inference output's full lineage envelope." }, "404": { "description": "No inference output with lineage at that seq." } }, "summary": "Upstream lineage: an inference output's provenance", "tags": [ "catalogue" ] } }, "/v1/desk/sessions": { "post": { "description": "With the bearer the identity-provider sign-in minted for a member of the desk staff (`POST /v1/portal/token`), open a `desk_session` at the house they work at — recorded as `desk_session.opened` under their principal — and answer with a desk bearer for them and the shift's unlock token. Both end with the shift: the sign-in's own expiry or `AERANDIL_STAFF_SESSION_TTL`, whichever is sooner. Refused to a machine principal, a token already minted for a desk session, a person with no staff record, an inactive one, and any role but the front office's. Not idempotency-keyed: the response is a credential, and the idempotency cache would keep it.", "operationId": "open_desk_session", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenDeskSessionRequest" } } }, "required": false }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeskSessionResponse" } } }, "description": "The shift is open.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not a front-office member of staff signed in through the identity provider." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No home property, several and none named, or a property they do not work at." } }, "summary": "Open a shift at the desk", "tags": [ "oauth" ] } }, "/v1/desk/sessions/{id}/close": { "post": { "description": "The desk signs out: the session closes (`desk_session.closed`) and no further token is minted for it. Only a bearer minted for this session may close it. Closing a closed session is a no-op.", "operationId": "close_desk_session", "parameters": [ { "description": "The `desk_session` id.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Closed.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The bearer was not minted for this desk session." } }, "summary": "End the shift", "tags": [ "oauth" ] } }, "/v1/desk/sessions/{id}/move": { "post": { "description": "The person at the desk takes it to another property they work at — one where a staff record claiming their identity has its home (`staff_works_at_property`): a new `desk_session` opens there as that record (`desk_session.opened`), ending when this one would have; this one closes (`desk_session.closed`); and the answer is a fresh bearer and unlock token for the new shift, running as that record with its role's scopes and no step-up carried. Only a bearer minted for this session may move it. A property the person has no staff record at is refused. Not idempotency-keyed: the response is a credential.", "operationId": "move_desk_session", "parameters": [ { "description": "The `desk_session` id.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveDeskSessionRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeskSessionResponse" } } }, "description": "The shift is open at the new house; the old one is closed.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`desk_session_ended`: the shift is closed or spent." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not this session's bearer, not a front-office member of staff, or a property they do not work at." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`already_at_property`." } }, "summary": "Move the shift to another house", "tags": [ "oauth" ] } }, "/v1/desk/sessions/{id}/passcode": { "post": { "description": "Public — a locked desk holds no bearer, only the shift's unlock token. With it, an employee and their passcode (the floor handset's passcode, under the same per-staff lockout): the person already at the desk unlocks or steps up (`desk_session.stepped_up`); another member of the property's desk staff takes the desk (`desk_session.switched`, under their own principal). Either way the answer is a fresh bearer for that person carrying a step-up window (`AERANDIL_DESK_STEP_UP_TTL`), inside which the step-up-gated verbs and markings are theirs. Every refusal about the person reads the same (`invalid_desk_credentials`); a session that has ended says so (`desk_session_ended`). Rate-limited per IP like `/oauth/token`.", "operationId": "prove_desk_passcode", "parameters": [ { "description": "The `desk_session` id.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeskPasscodeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeskSessionResponse" } } }, "description": "Proven; the bearer runs as the person at the desk.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`invalid_desk_credentials` (no detail by design) or `desk_session_ended`." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Neither or both of `employee_id` and `staff_member_id`, or no passcode." }, "429": { "description": "Per-IP rate limit exceeded (the `/oauth/token` limiter)." } }, "security": [], "summary": "Prove who is at the desk: unlock, step up, or switch", "tags": [ "oauth" ] } }, "/v1/erasure-requests": { "post": { "description": "Open a **pending** `erasure_request` for one `(object_type, object_id)` — the durable audit record of a right-to-erasure demand. Nothing is deleted yet: a second, separately-scoped principal decides the request via `.../approve` (which performs the hard delete) or `.../reject` (e.g. an Art. 17(3) retention carve-out applies). \n\n**Scope `erasure:write`** opens requests; `erasure:approve` decides them — the separation is the dual-control seam. \n\n**Tenant-scoped.** Naming another tenant's object returns `404`, indistinguishable from \"no such id\". \n\nPending requests are ordinary ontology objects: list them via the generic search route on `hospitality.erasure_request`. Idempotent via `Idempotency-Key`.", "operationId": "create_erasure_request", "parameters": [ { "description": "Opaque idempotency token (Stripe-shape). Repeated POSTs with the same key replay the original response within the cache TTL rather than creating a duplicate object.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErasureRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErasureRequestCreated" } } }, "description": "Pending erasure request opened.", "headers": { "Cache-Control": { "description": "Always `no-store`.", "schema": { "const": "no-store", "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No object with that `(object_type, object_id)` for this tenant." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Body invalid — `invalid_body` or `invalid_idempotency_key`." } }, "security": [ { "aerandil_oauth": [ "erasure:write" ] } ], "summary": "Open an Article 17 erasure request", "tags": [ "compliance" ] } }, "/v1/erasure-requests/{id}/approve": { "post": { "description": "Hard-delete the request's target object and every link involving it in one transaction, then record the decision on the request row. Requires `erasure:approve`. The erase happens before the record: a retried approve after a partial failure finds the target already absent and still records a truthful decision (`target_found = false`). `events` is never touched.", "operationId": "approve_erasure_request", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "decision_note": { "description": "Reviewer's note; recorded on the request row under the `internal.restricted` marking.", "type": "string" } }, "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErasureDecision" } } }, "description": "Decision recorded.", "headers": { "Cache-Control": { "description": "Always `no-store`.", "schema": { "const": "no-store", "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No such erasure request for this tenant." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Request already decided — `erasure_request_not_pending`." } }, "summary": "Approve an erasure request (performs the hard delete)", "tags": [ "compliance" ] } }, "/v1/erasure-requests/{id}/reject": { "post": { "description": "Refuse a pending erasure request — e.g. an Article 17(3) retention carve-out applies — recording who refused and why. The target object is untouched. Requires `erasure:approve`.", "operationId": "reject_erasure_request", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "decision_note": { "description": "Reviewer's note; recorded on the request row under the `internal.restricted` marking.", "type": "string" } }, "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErasureDecision" } } }, "description": "Decision recorded.", "headers": { "Cache-Control": { "description": "Always `no-store`.", "schema": { "const": "no-store", "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No such erasure request for this tenant." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Request already decided — `erasure_request_not_pending`." } }, "summary": "Reject an erasure request", "tags": [ "compliance" ] } }, "/v1/events": { "get": { "description": "Tail of the event log, oldest first. The `events` table is the architectural outbox — every accepted mutation appends one row in the same transaction as the projection update, so this endpoint *is* the CDC surface (webhooks sit on top of it). Keyset pagination on the BIGSERIAL `seq`; `cursor` is opaque base64url and wins over the numeric `since` alternative when both are present. `correlation_id` narrows to one action invocation's events; `object_type` matches both object events (subject type) and link events (either endpoint type); `property_id` narrows to one house plus the property-less events. The server-clamped `limit` defaults to 100 and caps at 1000. `order=desc` flips to newest-first for audit browsing: the cursor then pages strictly backwards through history and `since` is rejected.", "operationId": "list_events", "parameters": [ { "description": "Opaque base64url cursor from a prior response's `next_cursor`. Wins over `since` when both are set.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "Numeric `seq` alternative to `cursor` for clients that track `seq` themselves. Strict greater-than filter (`WHERE seq > since`). Must be non-negative.", "in": "query", "name": "since", "required": false, "schema": { "minimum": 0, "type": "integer" } }, { "description": "Narrow to events emitted under a specific correlation id (typically one action invocation).", "in": "query", "name": "correlation_id", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "description": "Narrow to events involving any of the given object types — one API name, or several comma-separated (`object_type=hospitality.room,hospitality.housekeeping_task`). Matches the subject type on object events and either endpoint type on link events.", "in": "query", "name": "object_type", "required": false, "schema": { "type": "string" } }, { "description": "Narrow to one property's events plus the property-less ones (tenant-level subjects such as a person, named events). An event's property is derived when it is appended, from its subject's tenancy scope — a link event takes its from endpoint's, else its to endpoint's — so a sibling property's events are what this excludes.", "in": "query", "name": "property_id", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "description": "Page size. Default 100, server-clamps to 1000.", "in": "query", "name": "limit", "required": false, "schema": { "maximum": 1000, "minimum": 1, "type": "integer" } }, { "description": "Sort order over `seq`. `asc` (default) is the CDC tail; `desc` is newest-first audit browsing, where `cursor` means strictly-less-than and `since` is rejected.", "in": "query", "name": "order", "required": false, "schema": { "default": "asc", "enum": [ "asc", "desc" ], "type": "string" } }, { "description": "Read a branch's own event stream instead of the main log (branch-and-time-travel §Branching). The `seq`/cursor namespace is the branch stream's own, distinct from the main log's; only the ascending tail is supported and the `correlation_id` / `object_type` / `property_id` / `order=desc` filters do not compose with it (422).", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsResponse" } } }, "description": "Page of events. `next_cursor` is omitted once the consumer catches up to the head of the log.", "headers": { "Cache-Control": { "description": "Always `no-store` — live data.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "description": "Validation error — invalid cursor / since / object_type / property_id / limit." } }, "security": [ { "aerandil_oauth": [ "events:read", "objects:read" ] } ], "summary": "List events", "tags": [ "events" ] } }, "/v1/events/stream": { "get": { "description": "Server-Sent Events tail of the event log. The polling endpoint at `GET /v1/events` is the right contract for batched durable consumers (replayable, indifferent to downtime); the streaming surface exists for *live* agents that can't afford the poll-sleep-poll latency. \n\nBoth surfaces emit the same `EventRow` shape — a client can swap between polling and streaming without re-tooling filters. \n\n**Resume.** The `Last-Event-ID` request header (auto-set by browser `EventSource` on reconnect) carries the last observed `seq` and wins over the `since` query parameter. \n\n**Frames.** The default frame has `id: ` and `data: `. An `error` frame (`event: error`) is emitted when an event row fails to serialise — the consumer reconnects with the last known `id`. Comment-only heartbeat frames (`: keepalive\\n\\n`) keep idle connections open across NAT/LB cull windows and are not modeled here (per the OAI registry, SSE comments are out of scope).", "operationId": "stream_events", "parameters": [ { "description": "Resume cursor (last observed `seq`). Set automatically by browser `EventSource` on reconnect; wins over the `since` query parameter when both are present.", "in": "header", "name": "Last-Event-ID", "required": false, "schema": { "pattern": "^\\d+$", "type": "string" } }, { "description": "Numeric `seq` resume cursor for SDKs that don't speak the standard `Last-Event-ID` reconnect header. Strict greater-than (`seq > since`). Loses to `Last-Event-ID` when both are set.", "in": "query", "name": "since", "required": false, "schema": { "minimum": 0, "type": "integer" } }, { "description": "Same shape as `/v1/events?correlation_id=…`.", "in": "query", "name": "correlation_id", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "description": "Same shape as `/v1/events?object_type=…`.", "in": "query", "name": "object_type", "required": false, "schema": { "type": "string" } }, { "description": "Same shape as `/v1/events?property_id=…` — the house a handset or desk is standing in.", "in": "query", "name": "property_id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/EventStreamFrame" }, "x-itemSchema": { "$ref": "#/components/schemas/EventStreamFrame" } } }, "description": "Open Server-Sent Events stream. Runs until the client disconnects; idle connections are kept alive by `: keepalive` comment frames every ~15 seconds.", "headers": { "Cache-Control": { "description": "Always `no-store` — forever-streaming body.", "schema": { "const": "no-store", "type": "string" } } } } }, "security": [ { "aerandil_oauth": [ "events:read", "objects:read" ] } ], "summary": "Stream events (Server-Sent Events)", "tags": [ "events" ] } }, "/v1/fnb/checks/{check_id}/card-payment": { "post": { "description": "Sends a registered Adyen terminal a Terminal API `PaymentRequest` for part of an open check's balance — with `tip_mode = on_terminal`, the terminal asks the guest for a tip (`tenderOption=AskGratuity`) — and records the approval as the check's payment through `add_check_payment` under the caller's own identity: `tender = card`, `amount` = the authorised total less the terminal's `TipAmount`, `tip`, `psp_reference`, `terminal_transaction_id`, `poiid`, `external_ref` = the `pspReference`. Authorised before the terminal is touched: the caller's `add_check_payment` scope, the house and (for a till) outlet gate, the check open and owing at least `amount`, and a dry run of the payment the kernel will record. **`Idempotency-Key` is required**: a lost answer is asked after (`TransactionStatusRequest`), and one the terminal still will not give answers `504 card_outcome_unknown` — check the terminal, then retry with the same key, which resumes the question rather than charging again. A terminal approval the kernel then refuses is reversed on the terminal (`ReversalRequest`) and answered `409`. `501` unless `AERANDIL_ADYEN_ENABLED=1`.", "operationId": "check_card_payment", "parameters": [ { "description": "The open `hospitality.guest_check` the card pays.", "in": "path", "name": "check_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckCardPaymentRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckCardPaymentResponse" } } }, "description": "The card was approved and the payment recorded on the check.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Nothing recorded: `check_not_open`, `amount_exceeds_balance`; `card_declined`, `card_cancelled`, `terminal_busy` (nothing charged); `card_reversed` — the terminal approved, the kernel refused (its reason in the message, its code in `parameters.kernel_code`) and the payment was reversed; `card_reversal_failed` — the same, but the reversal failed: the card was charged, refund `parameters.psp_reference` by hand or retry with the same key; `idempotency_in_flight`." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`idempotency_key_required`, `invalid_body`, `invalid_amount`, `currency_mismatch`, `device_not_active`, `device_missing_vendor_ref`, `terminal_rejected` (Adyen never delivered the message — e.g. an unknown POIID), `idempotency_key_mismatch`, or the kernel's refusal of the dry run (`invalid_action`)." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The Adyen bridge is not enabled on this deployment." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`terminal_unreachable` — the payment never reached the terminal, nothing was charged; `terminal_gateway_error` — the terminal refused the request itself." }, "504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`card_outcome_unknown` — the terminal has not said whether the card was charged. Check the terminal; a retry with the same `Idempotency-Key` asks again and records the payment if it was approved, never sending a second one." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.add_check_payment:apply" ] } ], "summary": "Take a check's card payment on an Adyen terminal", "tags": [ "fnb" ] } }, "/v1/fnb/receipts/{receipt_id}/epos": { "get": { "description": "The receipt's lines as an Epson ePOS-Print `` document (``, ``, ``) for a client printing on its own LAN. `drawer=1` adds the cash-drawer kick (``) — only when the receipt took cash. Deterministic: the same receipt is the same bytes. Read through `hospitality.function.fnb_receipt` under the caller's own context: its grant, the house gate, and — for a till — the till's own outlet (another outlet's receipt is `403 outlet_out_of_scope`).", "operationId": "fnb_receipt_epos", "parameters": [ { "description": "The `hospitality.check_receipt` a settled check was issued.", "in": "path", "name": "receipt_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "`1` adds the drawer kick, when the receipt took cash.", "in": "query", "name": "drawer", "required": false, "schema": { "enum": [ "0", "1" ], "type": "string" } } ], "responses": { "200": { "content": { "text/xml": { "schema": { "type": "string" } } }, "description": "The `` document.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.fnb_receipt:invoke" ] } ], "summary": "A receipt as Epson ePOS-Print XML", "tags": [ "fnb" ] } }, "/v1/fnb/receipts/{receipt_id}/print": { "post": { "description": "Queues the receipt for a registered printer (`hospitality.device`, `kind = printer`, `active`, at the receipt's house, with a poll credential). The printer fetches it on its next Server Direct Print poll (`POST /v1/print/epson/sdp`); the job is `queued`, then `printing` once handed over, then `printed` or `failed` as the printer reports. `drawer: true` kicks the cash drawer — only for a receipt that took cash, within ten minutes of its issue (a reprint never opens the drawer). `Idempotency-Key` makes a retried press one job. Read through `hospitality.function.fnb_receipt` under the caller's own context: its grant, the house gate, and — for a till — the till's own outlet (another outlet's receipt is `403 outlet_out_of_scope`).", "operationId": "fnb_print_receipt", "parameters": [ { "description": "The `hospitality.check_receipt` a settled check was issued.", "in": "path", "name": "receipt_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintReceiptRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintJob" } } }, "description": "The print job, queued.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`idempotency_in_flight`." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`invalid_body`, `device_not_printer`, `device_not_active`, `printer_not_configured` (no poll credential), `drawer_not_allowed`, `idempotency_key_mismatch`." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.fnb_receipt:invoke" ] } ], "summary": "Queue a receipt for the house's printer", "tags": [ "fnb" ] } }, "/v1/fnb/receipts/{receipt_id}/text": { "get": { "description": "The receipt as 42 columns of plain text (Font A on 80 mm paper) — the till's preview, line for line what the printer prints: the supplier's name, address and VAT number, the check, the time of supply, the lines, the total, VAT per rate (rate, net, VAT, VAT-inclusive total — VAT Notice 700 §16.6.1), the tenders and the receipt's number on the property's document chain. A pure function of the receipt's snapshot. Read through `hospitality.function.fnb_receipt` under the caller's own context: its grant, the house gate, and — for a till — the till's own outlet (another outlet's receipt is `403 outlet_out_of_scope`).", "operationId": "fnb_receipt_text", "parameters": [ { "description": "The `hospitality.check_receipt` a settled check was issued.", "in": "path", "name": "receipt_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "The receipt, 42 columns, one line feed per line.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.fnb_receipt:invoke" ] } ], "summary": "A receipt as plain text", "tags": [ "fnb" ] } }, "/v1/folios/{folio_id}/card-authorisations": { "post": { "description": "Authorises without capturing — the pre-arrival or check-in guarantee. Draws on a card already on file (`payment_card_id`, the path OPERA and Mews both take) or on a single-use `payment_method` token collected by a hosted surface and never kept. Never a PAN: the `payment_token_no_pan_shape` validator refuses anything Luhn-shaped, which is the structural half of the SAQ-A posture. The fraud assessment is filed against the booking behind the folio, or — for a group master or house account, which has none — against the folio itself, under the property it sits at. The hold records why it was placed (`purpose`, defaulted from the folio). A channel's virtual card is refused (`422 virtual_card_not_holdable`): it is charged once on its activation date, never held. Where the house takes part in Watchtower, the card rail's fraud network, a card the network blocks is refused before the processor is asked (`422 refused_by_watchtower`); its `parameters` name the answer (`fraud_network_signal_id`) the desk can contest and carry `guest_message`, the words a guest may be given — never the reason. `501` unless `AERANDIL_STRIPE_ENABLED=1`.", "operationId": "authorise_card_on_folio", "parameters": [ { "description": "The folio the hold guarantees.", "in": "path", "name": "folio_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardAuthorisationRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardAuthorisationResponse" } } }, "description": "The hold was taken and recorded as a payment leg.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`merchant_account_not_ready` — the property's card payments settle to its own merchant account, which Stripe has not yet let take charges." }, "422": { "$ref": "#/components/responses/Unprocessable" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No card rail is configured on this deployment." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`rail_unavailable` — the card processor could not be reached (a transport failure, a 5xx, a 429, or this request's key still running at the processor). A hold is never queued — the desk needs the issuer's answer now: check the guest in without one, or try again. Try again after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait before trying the same request again (RFC 9110 §10.2.3) — the queue's first backoff.", "schema": { "minimum": 0, "type": "integer" } } } } }, "summary": "Hold an amount against a card", "tags": [ "finance" ] } }, "/v1/folios/{folio_id}/invoice": { "post": { "description": "Turns a sealed folio into the numbered document its recipient keeps, then renders and stores the PDF. Accepts a closed folio at zero balance (the settled stay) and an open folio already transferred to a company's A/R account (the billed stay, which this seals as it issues). **A failed upload is not a failed request.** The number is allocated and the document exists the moment the action commits; `pdf_stored` reports whether the rendering also reached object storage, and `GET /v1/invoices/{invoice_id}/pdf` renders on demand when it did not. Retry-safe without an `Idempotency-Key`: the route re-reads first, and a folio that already carries an uncredited invoice answers with that document and `already_issued: true` rather than asking the series for a second number.", "operationId": "issue_invoice_for_folio", "parameters": [ { "description": "The folio to project into a document.", "in": "path", "name": "folio_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueInvoiceRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueInvoiceResponse" } } }, "description": "Issued.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The folio cannot be invoiced. The reason is one of `INVOICE_BLOCKERS`: `already_invoiced`, `folio_open`, `folio_not_invoiceable`, `recipient_address_missing`, `recipient_unknown`, `issuer_not_configured`, `folio_empty`, `rebate_not_a_credit`. `preview_invoice` returns the same list without allocating anything." } }, "summary": "Issue the invoice for a folio", "tags": [ "finance" ] } }, "/v1/folios/{folio_id}/invoice-preview": { "get": { "description": "The document the recipient would get, rendered from the live folio with no number and a watermark saying it is not a tax invoice. Writes nothing and allocates no number. Runs the same `assess()` as `issue_invoice`, so what it shows and what would be issued cannot disagree; a folio that cannot be invoiced answers `409` naming the blockers rather than rendering an empty page.", "operationId": "folio_invoice_preview", "parameters": [ { "description": "The folio to project into a document.", "in": "path", "name": "folio_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "The property's business date the pro forma is dated. Required for the same reason `issue_invoice` requires it — a document's date is a fact about the property's day, not the server's clock.", "in": "query", "name": "issued_on", "required": true, "schema": { "format": "date", "type": "string" } }, { "description": "Bill the guest or the company.", "in": "query", "name": "recipient_kind", "required": false, "schema": { "enum": [ "person", "company" ], "type": "string" } } ], "responses": { "200": { "content": { "application/pdf": { "schema": { "format": "binary", "type": "string" } } }, "description": "The document, as a PDF.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`folio_not_invoiceable` — the message names every blocker that applies." } }, "summary": "Render the pro forma for a folio", "tags": [ "finance" ] } }, "/v1/fraud-risk-assessments/{assessment_id}/block": { "post": { "description": "The desk decides a hold in review (`card_checks`) against the guest. Three effects in one call: the hold's review `declined` (`resolve_payment_review`); the hold voided at the processor (`fraudulent`), or queued (`202`-style `release: queued`) when it cannot be reached; and, only with `report_to_network`, the outcome given to Watchtower as the house's `confirmed_fraud`, digested server-side. The decision is recorded first; a release that then fails leaves the hold `blocked_still_held` on the queue, and the same call releases it. A report the network refuses (the house does not take part, or the assessment rests on a network answer that matched) is `reported: false` with `report_note`, not an error: the block stands. Only a caller cleared to read `internal.restricted` decides (`403 insufficient_clearance` otherwise, before anything is read or released). Keeping a hold is `POST /v1/fraud-risk-assessments/{assessment_id}/keep`.", "operationId": "block_assessed_hold", "parameters": [ { "description": "The hold's gating fraud_risk_assessment.", "in": "path", "name": "assessment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudAssessmentBlockRequest" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudAssessmentBlockResponse" } } }, "description": "Blocked; the hold released, queued or already gone.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`already_decided` — the hold was kept, or was never held for review; only a hold still held for review, or one already declined, can be blocked." }, "422": { "$ref": "#/components/responses/Unprocessable" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No card rail is configured on this deployment." } }, "security": [ { "aerandil_oauth": [ "actions:apply", "markings:internal.restricted:read" ] }, { "aerandil_oauth": [ "actions:hospitality.action.resolve_payment_review:apply", "actions:hospitality.action.void_authorisation:apply", "markings:internal.restricted:read" ] } ], "summary": "Block a held card the desk reviewed", "tags": [ "finance" ] } }, "/v1/fraud-risk-assessments/{assessment_id}/keep": { "post": { "description": "The desk decides a hold in review (`card_checks`) for the guest: the hold's review `approved` (`resolve_payment_review`), the hold left to be captured at check-out as any other. Nothing is sent to the processor. Only a caller cleared to read `internal.restricted` decides, because the assessment behind the hold is marked so (`card_checks` says so as `may_decide`); anyone else is refused with `403 insufficient_clearance` before anything is read. A hold already kept answers as kept.", "operationId": "keep_assessed_hold", "parameters": [ { "description": "The hold's gating fraud_risk_assessment.", "in": "path", "name": "assessment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudAssessmentKeepResponse" } } }, "description": "Kept; the hold stands, to be captured at check-out.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`already_decided` — the hold was blocked, or was never held for review; only a hold still held for review can be kept." }, "422": { "$ref": "#/components/responses/Unprocessable" } }, "security": [ { "aerandil_oauth": [ "actions:apply", "markings:internal.restricted:read" ] }, { "aerandil_oauth": [ "actions:hospitality.action.resolve_payment_review:apply", "markings:internal.restricted:read" ] } ], "summary": "Keep a held card the desk reviewed", "tags": [ "finance" ] } }, "/v1/function-types": { "get": { "description": "Schema-discovery surface for read-only functions. Each entry surfaces the target object type, parameter count, and the function's declared return-type kind so a UI can render a function picker without walking `/v1/openapi.json`.", "operationId": "list_function_types", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "$ref": "#/components/schemas/FunctionTypeSummary" }, "type": "array" }, "next_page_token": { "description": "Opaque cursor for the next page (AIP-158). Reserved for future growth; v1 returns `null` because the registry size is bounded.", "nullable": true, "type": "string" } }, "required": [ "data" ], "type": "object" } } }, "description": "Sorted summary list of every registered function type." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "List function types", "tags": [ "metadata" ] } }, "/v1/functions/hospitality.function.arrivals_board/invoke": { "post": { "description": "The house's arrivals for a date as Ithaca's arrivals board reads them: every reservation arriving that day that is confirmed, held, modified or already in house. `date` defaults to the house's hotel date (`hotel_date`). Per arrival: the reservation and its confirmation number, its status, the guest (`guest_id`, `guest_name`), the stay's dates and party, any special requests, `has_special_request` (true when the stay carries a request, whether or not this reader may see the text, which is health-marked), the deposit required and paid, and `readiness`: `unassigned` when a room leg has no room, `not_ready` when no assigned room can take the guest yet, `ready` when one can, `in_house` once checked in. Per live room leg in `rooms`: its id (the target `assign_room_for_reservation_room` and `room_candidates` take), the booked room type, and once assigned the room with its number, housekeeping status and occupancy, any status block its window meets, and `ready`: clean or inspected, vacant, and not out of order for the stay. Ordered as the desk works it: unassigned, then not ready, then ready, then in house, by guest within each. Guest names are personal data: a reader not cleared for them gets the rows without them. Read-only.", "operationId": "invoke_hospitality_function_arrivals_board", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "date": { "format": "date", "title": "The arrival date to read; the house's hotel date when omitted", "type": "string" } }, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "properties": { "arrivals": { "items": { "properties": { "adults": { "type": "integer" }, "arrival_date": { "format": "date", "type": "string" }, "children": { "type": "integer" }, "confirmation_number": { "type": "string" }, "departure_date": { "format": "date", "type": "string" }, "deposit_paid_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "deposit_required_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "guest_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.person" }, "guest_name": { "type": "string" }, "has_special_request": { "type": "boolean" }, "readiness": { "enum": [ "unassigned", "not_ready", "ready", "in_house" ], "type": "string" }, "reservation_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "rooms": { "items": { "properties": { "block": { "enum": [ "out_of_order", "out_of_service" ], "type": "string" }, "housekeeping_status": { "type": "string" }, "occupancy": { "type": "string" }, "ready": { "type": "boolean" }, "reservation_room_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation_room" }, "room_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.room" }, "room_number": { "type": "string" }, "room_type_code": { "type": "string" }, "room_type_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.room_type" } }, "required": [ "reservation_room_id", "ready" ], "type": "object" }, "type": "array" }, "special_requests": { "type": "string" }, "status": { "type": "string" } }, "required": [ "reservation_id", "status", "readiness", "has_special_request", "rooms" ], "type": "object" }, "type": "array" }, "date": { "format": "date", "type": "string" } }, "required": [ "date", "arrivals" ], "type": "object" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.arrivals_board:invoke" ] } ], "summary": "Arrivals board", "tags": [ "organization" ] } }, "/v1/functions/hospitality.function.arrivals_board/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_arrivals_board`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_arrivals_board", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "date": { "format": "date", "title": "The arrival date to read; the house's hotel date when omitted", "type": "string" } }, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Arrivals board (dry-run)", "tags": [ "organization" ] } }, "/v1/functions/hospitality.function.board_sort/invoke": { "post": { "description": "The order the caller reads one of the property's boards in — hubOS's server-defined sort pattern with its per-user override: the caller's own preference for the board when their session is a staff member who set one (`set_staff_sort_preference`), else the house's active pattern (`set_board_sort_pattern`), else the kernel's default (the sheet: status, priority, task type, room; the rack: floor, room; work orders: severity, due date, room; pacing: credits still to clean, name). `source` says which (staff, property, kernel) and `pattern_id` names the house's pattern. `keys` is ordered, first key first, each with its direction; every ranked key (priority — a work order's severity — task_type, status) carries `values`, its whole vocabulary least first: the stated order, then the rest in the kernel's rank. A row with no value for a key sorts after the rows with one, in either direction. The kernel names the order; the client applies it to its rows. Name one `board` and the answer carries its `board`, `source`, `pattern_id` and `keys` beside `property_id`; name several as `boards` and `boards` in the answer is a map from each board to that answer, so a handset reads every board its role shows in one call. Exactly one of the two. Read-only.", "operationId": "invoke_hospitality_function_board_sort", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "board": { "enum": [ "housekeeping_sheet", "housekeeping_rack", "work_orders", "pacing" ], "title": "The board: housekeeping_sheet, housekeeping_rack, work_orders or pacing", "type": "string" }, "boards": { "items": { "enum": [ "housekeeping_sheet", "housekeeping_rack", "work_orders", "pacing" ], "type": "string" }, "title": "Several boards in one read (instead of `board`)", "type": "array" } }, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "properties": { "board": { "enum": [ "housekeeping_sheet", "housekeeping_rack", "work_orders", "pacing" ], "type": "string" }, "boards": { "properties": { "housekeeping_rack": { "properties": { "board": { "enum": [ "housekeeping_sheet", "housekeeping_rack", "work_orders", "pacing" ], "type": "string" }, "keys": { "items": { "properties": { "direction": { "enum": [ "asc", "desc" ], "type": "string" }, "key": { "enum": [ "priority", "room_number", "floor", "task_type", "status", "due_at", "credits", "arrival_time", "departure_time", "pending_credits", "target_percent", "name" ], "type": "string" }, "values": { "items": { "type": "string" }, "type": "array" } }, "required": [ "key", "direction" ], "type": "object" }, "type": "array" }, "pattern_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.board_sort_pattern" }, "source": { "enum": [ "staff", "property", "kernel" ], "type": "string" } }, "required": [ "board", "source", "keys" ], "type": "object" }, "housekeeping_sheet": { "properties": { "board": { "enum": [ "housekeeping_sheet", "housekeeping_rack", "work_orders", "pacing" ], "type": "string" }, "keys": { "items": { "properties": { "direction": { "enum": [ "asc", "desc" ], "type": "string" }, "key": { "enum": [ "priority", "room_number", "floor", "task_type", "status", "due_at", "credits", "arrival_time", "departure_time", "pending_credits", "target_percent", "name" ], "type": "string" }, "values": { "items": { "type": "string" }, "type": "array" } }, "required": [ "key", "direction" ], "type": "object" }, "type": "array" }, "pattern_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.board_sort_pattern" }, "source": { "enum": [ "staff", "property", "kernel" ], "type": "string" } }, "required": [ "board", "source", "keys" ], "type": "object" }, "pacing": { "properties": { "board": { "enum": [ "housekeeping_sheet", "housekeeping_rack", "work_orders", "pacing" ], "type": "string" }, "keys": { "items": { "properties": { "direction": { "enum": [ "asc", "desc" ], "type": "string" }, "key": { "enum": [ "priority", "room_number", "floor", "task_type", "status", "due_at", "credits", "arrival_time", "departure_time", "pending_credits", "target_percent", "name" ], "type": "string" }, "values": { "items": { "type": "string" }, "type": "array" } }, "required": [ "key", "direction" ], "type": "object" }, "type": "array" }, "pattern_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.board_sort_pattern" }, "source": { "enum": [ "staff", "property", "kernel" ], "type": "string" } }, "required": [ "board", "source", "keys" ], "type": "object" }, "work_orders": { "properties": { "board": { "enum": [ "housekeeping_sheet", "housekeeping_rack", "work_orders", "pacing" ], "type": "string" }, "keys": { "items": { "properties": { "direction": { "enum": [ "asc", "desc" ], "type": "string" }, "key": { "enum": [ "priority", "room_number", "floor", "task_type", "status", "due_at", "credits", "arrival_time", "departure_time", "pending_credits", "target_percent", "name" ], "type": "string" }, "values": { "items": { "type": "string" }, "type": "array" } }, "required": [ "key", "direction" ], "type": "object" }, "type": "array" }, "pattern_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.board_sort_pattern" }, "source": { "enum": [ "staff", "property", "kernel" ], "type": "string" } }, "required": [ "board", "source", "keys" ], "type": "object" } }, "type": "object" }, "keys": { "items": { "properties": { "direction": { "enum": [ "asc", "desc" ], "type": "string" }, "key": { "enum": [ "priority", "room_number", "floor", "task_type", "status", "due_at", "credits", "arrival_time", "departure_time", "pending_credits", "target_percent", "name" ], "type": "string" }, "values": { "items": { "type": "string" }, "type": "array" } }, "required": [ "key", "direction" ], "type": "object" }, "type": "array" }, "pattern_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.board_sort_pattern" }, "property_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.property" }, "source": { "enum": [ "staff", "property", "kernel" ], "type": "string" } }, "required": [ "property_id" ], "type": "object" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.board_sort:invoke" ] } ], "summary": "Board sort", "tags": [ "organization" ] } }, "/v1/functions/hospitality.function.board_sort/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_board_sort`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_board_sort", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "board": { "enum": [ "housekeeping_sheet", "housekeeping_rack", "work_orders", "pacing" ], "title": "The board: housekeeping_sheet, housekeeping_rack, work_orders or pacing", "type": "string" }, "boards": { "items": { "enum": [ "housekeeping_sheet", "housekeeping_rack", "work_orders", "pacing" ], "type": "string" }, "title": "Several boards in one read (instead of `board`)", "type": "array" } }, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Board sort (dry-run)", "tags": [ "organization" ] } }, "/v1/functions/hospitality.function.card_checks/invoke": { "post": { "description": "The desk's review queue for the card rail's holds, and the Watchtower refusals it may still act on. `to_review`: every hold still standing (payment `pending`) that the rail held for the house's decision (`review_state = held`, placed with `manual_capture_after_review` because its assessment recommended review: Radar's manual review, or a band the network lifted), oldest first, and every hold the desk declined whose release has not gone through (`blocked_still_held`). Each carries the payment, amount, booking, guest, card, the hold's deadline (`decide_by`), the network's floor when its answer matched, `reportable` (blocking it may also give the outcome to the network: the house takes part, and the assessment rests on its own evidence rather than a network answer that matched) and `reported`; the band and Radar's risk level only for a caller cleared for `internal.restricted`. The decision is `resolve_payment_review`, apart from any capture, as a Radar Review closes apart from the PaymentIntent. `refused`: the network's refusals of the last 31 days, newest first, each with its answer, floor basis, booking, guest and whether the desk contested it. `participates` says whether the house takes part in Watchtower. `may_decide` says whether this caller may keep or block a hold: only one cleared to read `internal.restricted`, the assessment it decides on (a front desk sees the queue read-only, waiting on a manager). Read-only.", "operationId": "invoke_hospitality_function_card_checks", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "property_id" ], "type": "object" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "properties": { "as_of": { "format": "date-time", "type": "string" }, "may_decide": { "type": "boolean" }, "participates": { "type": "boolean" }, "refused": { "items": { "properties": { "assessment_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.fraud_risk_assessment" }, "confirmation_number": { "type": "string" }, "contested": { "type": "boolean" }, "contested_at": { "format": "date-time", "type": "string" }, "floor_basis": { "enum": [ "none", "contact", "card_unconfirmed", "card_corroborated", "card_own_house", "desk_override" ], "type": "string" }, "guest_name": { "type": "string" }, "issued_at": { "format": "date-time", "type": "string" }, "reservation_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "signal_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.fraud_network_signal" } }, "required": [ "assessment_id", "issued_at", "contested" ], "type": "object" }, "type": "array" }, "to_review": { "items": { "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "assessment_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.fraud_risk_assessment" }, "band": { "enum": [ "low", "medium", "high", "block", "not_assessed" ], "type": "string" }, "card_brand": { "type": "string" }, "card_last4": { "type": "string" }, "confirmation_number": { "type": "string" }, "decide_by": { "format": "date-time", "type": "string" }, "guest_name": { "type": "string" }, "issued_at": { "format": "date-time", "type": "string" }, "network_floor_basis": { "enum": [ "none", "contact", "card_unconfirmed", "card_corroborated", "card_own_house", "desk_override" ], "type": "string" }, "payment_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.payment" }, "radar_risk_level": { "type": "string" }, "reportable": { "type": "boolean" }, "reported": { "type": "boolean" }, "reservation_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "state": { "enum": [ "review", "blocked_still_held" ], "type": "string" } }, "required": [ "assessment_id", "payment_id", "state", "issued_at", "reportable", "reported" ], "type": "object" }, "type": "array" } }, "required": [ "as_of", "participates", "may_decide", "to_review", "refused" ], "type": "object" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.card_checks:invoke" ] } ], "summary": "Card checks", "tags": [ "hospitality" ] } }, "/v1/functions/hospitality.function.card_checks/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_card_checks`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_card_checks", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "property_id" ], "type": "object" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Card checks (dry-run)", "tags": [ "hospitality" ] } }, "/v1/functions/hospitality.function.checklist_for_task/invoke": { "post": { "description": "The checklist a housekeeping task resolves to — the most specific active template for its task type and its room's type: the house's for the room's type, the house's for every room, the brand's for the room's type, the brand's for every room (oldest template first within a tier). The same resolution `complete_housekeeping_task` gates on and `record_checklist_result` answers, so a handset reads the list instead of re-deriving it. Returns the template's id, name, items (code, label, kind) and whether it is required for completion, and the id of the result recorded against the task for it; no `template` when no list applies. Read-only.", "operationId": "invoke_hospitality_function_checklist_for_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "properties": { "result_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.checklist_result" }, "task_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.housekeeping_task" }, "template": { "properties": { "id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.checklist_template" }, "items": { "items": { "properties": { "code": { "type": "string" }, "kind": { "enum": [ "check", "photo", "count", "text" ], "type": "string" }, "label": { "type": "string" } }, "required": [ "code", "label", "kind" ], "type": "object" }, "type": "array" }, "name": { "type": "string" }, "required_for_completion": { "type": "boolean" } }, "required": [ "id", "name", "items", "required_for_completion" ], "type": "object" } }, "required": [ "task_id" ], "type": "object" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.checklist_for_task:invoke" ] } ], "summary": "Checklist for a task", "tags": [ "operations" ] } }, "/v1/functions/hospitality.function.checklist_for_task/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_checklist_for_task`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_checklist_for_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Checklist for a task (dry-run)", "tags": [ "operations" ] } }, "/v1/functions/hospitality.function.fetch_federated_output_card/invoke": { "post": { "description": "Return the participant-safe card for a published federated output: cohort summary, aggregate values, privacy guarantee, suppression state, applicability statement, and downstream-use restrictions. Draft, revoked, expired, and quarantined outputs are not served.", "operationId": "invoke_hospitality_function_fetch_federated_output_card", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "output_id": { "format": "uuid", "title": "Federated output id", "type": "string", "x-aerandil-references": "hospitality.federated_output" } }, "required": [ "output_id" ], "type": "object" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "properties": { "applicability_statement": { "type": "string" }, "artifact_hash": { "type": "string" }, "artifact_reference": { "type": "string" }, "cohort_summary": {}, "confidence_intervals": {}, "datasheet_reference": { "type": "string" }, "downstream_use_restrictions": { "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "metric_values": {}, "model_card_reference": { "type": "string" }, "output_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.federated_output" }, "output_kind": { "enum": [ "benchmark_report", "calibration_curve", "aggregate_metric", "model_artifact", "signal_package", "governance_card" ], "type": "string" }, "output_schema_version": { "type": "string" }, "privacy_guarantee_summary": {}, "published_at": { "format": "date-time", "type": "string" }, "published_to_scope": { "enum": [ "program_owner", "participants", "public_aggregate", "specific_recipients" ], "type": "string" }, "run_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.federated_run" }, "suppression_applied": { "type": "boolean" }, "suppression_reasons": { "items": { "enum": [ "minimum_tenants_not_met", "minimum_properties_not_met", "minimum_subjects_not_met", "max_contributor_share_exceeded", "privacy_budget_exhausted", "high_variance", "data_quality_mismatch", "legal_basis_missing", "participant_withdrawal", "reviewer_blocked", "security_incident" ], "type": "string" }, "type": "array" } }, "required": [ "output_id", "run_id", "output_kind", "output_schema_version", "cohort_summary", "privacy_guarantee_summary", "suppression_applied", "suppression_reasons", "applicability_statement", "downstream_use_restrictions", "published_to_scope" ], "type": "object" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.fetch_federated_output_card:invoke" ] } ], "summary": "Fetch federated output card", "tags": [ "hospitality" ] } }, "/v1/functions/hospitality.function.fetch_federated_output_card/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_fetch_federated_output_card`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_fetch_federated_output_card", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "output_id": { "format": "uuid", "title": "Federated output id", "type": "string", "x-aerandil-references": "hospitality.federated_output" } }, "required": [ "output_id" ], "type": "object" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Fetch federated output card (dry-run)", "tags": [ "hospitality" ] } }, "/v1/functions/hospitality.function.find_booking/invoke": { "post": { "description": "One booking at a house by its confirmation number, whatever its status: arriving, in house, departed or cancelled. An exact match, so an unknown number returns no `bookings` and is not an error. Each booking is the row `arrivals_board` shows: the reservation, its status, the guest (`guest_id`, `guest_name`), the stay's dates and party, deposits, `has_special_request`, and in `rooms` each live leg with its id and any assigned room. `readiness` is present only for a stay still on the board. It carries no contact details. The number and the guest's name are personal data: a reader not cleared for them finds nothing, however exact the number. Read-only.", "operationId": "invoke_hospitality_function_find_booking", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "confirmation_number": { "title": "The booking's confirmation number, exactly as it was issued", "type": "string" } }, "required": [ "confirmation_number" ], "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "properties": { "bookings": { "items": { "properties": { "adults": { "type": "integer" }, "arrival_date": { "format": "date", "type": "string" }, "children": { "type": "integer" }, "confirmation_number": { "type": "string" }, "departure_date": { "format": "date", "type": "string" }, "deposit_paid_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "deposit_required_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "guest_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.person" }, "guest_name": { "type": "string" }, "has_special_request": { "type": "boolean" }, "readiness": { "enum": [ "unassigned", "not_ready", "ready", "in_house" ], "type": "string" }, "reservation_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "rooms": { "items": { "properties": { "block": { "enum": [ "out_of_order", "out_of_service" ], "type": "string" }, "housekeeping_status": { "type": "string" }, "occupancy": { "type": "string" }, "ready": { "type": "boolean" }, "reservation_room_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation_room" }, "room_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.room" }, "room_number": { "type": "string" }, "room_type_code": { "type": "string" }, "room_type_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.room_type" } }, "required": [ "reservation_room_id", "ready" ], "type": "object" }, "type": "array" }, "special_requests": { "type": "string" }, "status": { "type": "string" } }, "required": [ "reservation_id", "status", "has_special_request", "rooms" ], "type": "object" }, "type": "array" } }, "required": [ "bookings" ], "type": "object" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.find_booking:invoke" ] } ], "summary": "Find booking", "tags": [ "organization" ] } }, "/v1/functions/hospitality.function.find_booking/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_find_booking`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_find_booking", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "confirmation_number": { "title": "The booking's confirmation number, exactly as it was issued", "type": "string" } }, "required": [ "confirmation_number" ], "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Find booking (dry-run)", "tags": [ "organization" ] } }, "/v1/functions/hospitality.function.fnb_breakfast_roster/invoke": { "post": { "description": "The breakfast roster at the target outlet on `business_date` (default: the house's hotel date): one row per in-house stay whose live package includes a breakfast that day at this outlet — a component with a frozen `daypart` of `breakfast` or `brunch`, eaten the morning after the night that carries it, at one of its alternate outlets (any outlet of the house when it names none) — and per stay that checked out that morning having taken it. Guests without one are not rows; they pay on a check. Per row: the stay, its reservation, the room, the guests' names, the covers the package feeds (`entitled_covers`: the room's adults for a per-adult allowance, everyone in it otherwise), the component, the day's `allowance` and what is `remaining` of it (strings in `currency`), the covers already `taken_covers` — by the roster's tick-off (`record_breakfast_taken`) or a room charge that consumed it — the latest consumption and the check it came from (null for a tick-off), every consumption that day (`consumptions`), and the `status`: `expected`, `partial`, `taken`, or `no_show` (nothing eaten and the day is over, or the night audit settled it). Ordered by room. The target is the outlet, so a till reads its own outlet's roster only. Guest names are personal data: a reader not cleared for them gets the rows without them. Read-only.", "operationId": "invoke_hospitality_function_fnb_breakfast_roster", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date of the breakfast (defaults to the house's hotel date)", "type": "string" } }, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.outlet" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "properties": { "business_date": { "format": "date", "type": "string" }, "outlet_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "rows": { "items": { "properties": { "allowance": { "type": "string" }, "check_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.guest_check" }, "component_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.package_component" }, "consumption_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.package_component_consumption" }, "consumptions": { "items": { "properties": { "amount": { "type": "string" }, "check_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.guest_check" }, "consumption_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.package_component_consumption" }, "covers": { "type": "integer" }, "recorded_at": { "format": "date-time", "type": "string" } }, "required": [ "consumption_id" ], "type": "object" }, "type": "array" }, "currency": { "type": "string" }, "entitled_covers": { "type": "integer" }, "guest_names": { "items": { "type": "string" }, "type": "array" }, "remaining": { "type": "string" }, "reservation_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "room": { "type": "string" }, "status": { "enum": [ "expected", "taken", "partial", "no_show" ], "type": "string" }, "stay_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.stay" }, "taken_covers": { "type": "integer" } }, "required": [ "stay_id", "guest_names", "entitled_covers", "taken_covers", "status", "consumptions" ], "type": "object" }, "type": "array" } }, "required": [ "outlet_id", "business_date", "rows" ], "type": "object" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.fnb_breakfast_roster:invoke" ] } ], "summary": "F&B breakfast roster", "tags": [ "revenue" ] } }, "/v1/functions/hospitality.function.fnb_breakfast_roster/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_fnb_breakfast_roster`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_fnb_breakfast_roster", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date of the breakfast (defaults to the house's hotel date)", "type": "string" } }, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.outlet" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate F&B breakfast roster (dry-run)", "tags": [ "revenue" ] } }, "/v1/functions/hospitality.function.fnb_check_detail/invoke": { "post": { "description": "One check as the till and the receipt read it. `check`: its header — number, status, order kind, daypart, business date, covers, table, outlet, server, when it opened and settled — and every total (`subtotal`, `tax_total`, `total_due`, `paid_total`, `tip_total`, `balance_due`, strings in `currency`). `lines`: every line in the order it rang, voided and comped ones included with their reasons, each with its item and variant names, quantity, course, seat, unit price, line total, VAT, revenue category, tax class and kitchen `instructions`, and its modifier lines nested beneath it as `modifiers` (each with the `prefix` its option was chosen with; a modifier line's quantity already includes its parent's). `tickets`: the check's kitchen tickets, oldest fired first — id, ticket number, status, course, station (none = the unrouted expo ticket), fired and bumped — so a till with no kitchen screen bumps what it fired and the check can close. `payments`: each tender with its amount, tip, cash tendered and change, the card terminal's references, the folio a room charge posted to with its reservation and the guest who signed, when it was taken and by whom, and a manager's override of the stay's posting rules (`override_kind` no_post / no_credit, `authorised_by` — the manager signed in — and `override_reason`; null when none). `vat`: per rate over the live lines, the receipt's figures (VAT Notice 700 §16.6.1) — `code`, `rate`, `net`, `tax` and `gross`. `receipt`: once the check has settled, the receipt it was issued (`id`, `number`, `content_hash`, `issued_at` — read it whole with `fnb_receipt`), else null. The target is the check, so a house-bound bearer reads its own house's — and a till its own outlet's — only. Read-only.", "operationId": "invoke_hospitality_function_fnb_check_detail", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "properties": { "check": { "properties": { "balance_due": { "type": "string" }, "business_date": { "format": "date", "type": "string" }, "cleared_at": { "format": "date-time", "type": "string" }, "conveyance": { "enum": [ "tray", "trolley" ], "type": "string" }, "covers": { "type": "integer" }, "currency": { "type": "string" }, "daypart": { "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "type": "string" }, "delivered_at": { "format": "date-time", "type": "string" }, "delivery_status": { "enum": [ "taken", "dispatched", "delivered", "cleared" ], "type": "string" }, "dispatched_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.guest_check" }, "number": { "type": "string" }, "opened_at": { "format": "date-time", "type": "string" }, "order_kind": { "enum": [ "dine_in", "takeaway", "room_service", "delivery" ], "type": "string" }, "outlet_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "paid_total": { "type": "string" }, "promised_at": { "format": "date-time", "type": "string" }, "room": { "type": "string" }, "runner_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "server_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "settled_at": { "format": "date-time", "type": "string" }, "status": { "enum": [ "open", "settled" ], "type": "string" }, "subtotal": { "type": "string" }, "table_label": { "type": "string" }, "tax_total": { "type": "string" }, "tip_total": { "type": "string" }, "total_due": { "type": "string" } }, "required": [ "id", "number", "status", "order_kind", "opened_at" ], "type": "object" }, "lines": { "items": { "properties": { "comp_reason": { "type": "string" }, "course_number": { "type": "integer" }, "id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.check_line" }, "instructions": { "items": { "type": "string" }, "type": "array" }, "line_number": { "type": "string" }, "line_total": { "type": "string" }, "menu_item_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.menu_item" }, "modifiers": { "items": { "properties": { "comp_reason": { "type": "string" }, "course_number": { "type": "integer" }, "id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.check_line" }, "instructions": { "items": { "type": "string" }, "type": "array" }, "line_number": { "type": "string" }, "line_total": { "type": "string" }, "menu_item_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.menu_item" }, "name": { "type": "string" }, "notes": { "type": "string" }, "prefix": { "enum": [ "no", "extra", "light", "side" ], "type": "string" }, "quantity": { "type": "integer" }, "revenue_category": { "enum": [ "food", "non_alcoholic_beverage", "alcoholic_beverage", "other" ], "type": "string" }, "seat_number": { "type": "integer" }, "status": { "enum": [ "entered", "fired", "fulfilled", "voided", "comped" ], "type": "string" }, "tax_amount": { "type": "string" }, "tax_class": { "type": "string" }, "unit_price": { "type": "string" }, "variant_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.menu_item_variant" }, "variant_name": { "type": "string" }, "void_reason": { "type": "string" } }, "required": [ "id", "line_number", "status", "quantity", "course_number", "unit_price", "line_total", "tax_amount", "revenue_category", "tax_class", "instructions" ], "type": "object" }, "type": "array" }, "name": { "type": "string" }, "notes": { "type": "string" }, "quantity": { "type": "integer" }, "revenue_category": { "enum": [ "food", "non_alcoholic_beverage", "alcoholic_beverage", "other" ], "type": "string" }, "seat_number": { "type": "integer" }, "status": { "enum": [ "entered", "fired", "fulfilled", "voided", "comped" ], "type": "string" }, "tax_amount": { "type": "string" }, "tax_class": { "type": "string" }, "unit_price": { "type": "string" }, "variant_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.menu_item_variant" }, "variant_name": { "type": "string" }, "void_reason": { "type": "string" } }, "required": [ "id", "line_number", "status", "quantity", "course_number", "unit_price", "line_total", "tax_amount", "revenue_category", "tax_class", "instructions", "modifiers" ], "type": "object" }, "type": "array" }, "payments": { "items": { "properties": { "allowance_applied": { "type": "string" }, "amount": { "type": "string" }, "authorised_by": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "change_given": { "type": "string" }, "consumption_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.package_component_consumption" }, "folio_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.folio" }, "guest_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.person" }, "id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.check_payment" }, "override_kind": { "enum": [ "no_post", "no_credit" ], "type": "string" }, "override_reason": { "type": "string" }, "paid_at": { "format": "date-time", "type": "string" }, "poiid": { "type": "string" }, "psp_reference": { "type": "string" }, "reservation_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "staff_member_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "tender": { "enum": [ "room_charge", "cash", "card", "comp", "external", "charge_to_key" ], "type": "string" }, "tendered": { "type": "string" }, "terminal_transaction_id": { "type": "string" }, "tip": { "type": "string" } }, "required": [ "id", "tender", "amount", "tip", "paid_at" ], "type": "object" }, "type": "array" }, "receipt": { "properties": { "content_hash": { "type": "string" }, "id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.check_receipt" }, "issued_at": { "format": "date-time", "type": "string" }, "number": { "type": "string" } }, "required": [ "id", "number", "content_hash", "issued_at" ], "type": "object" }, "stay": { "properties": { "folio_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.folio" }, "guest_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.person" }, "guest_names": { "items": { "type": "string" }, "type": "array" }, "reservation_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "room": { "type": "string" }, "stay_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.stay" } }, "required": [ "stay_id", "guest_names" ], "type": "object" }, "tickets": { "items": { "properties": { "bumped_at": { "format": "date-time", "type": "string" }, "course_number": { "type": "integer" }, "fired_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.kitchen_ticket" }, "station_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.prep_station" }, "station_name": { "type": "string" }, "status": { "enum": [ "fired", "bumped", "recalled" ], "type": "string" }, "ticket_number": { "type": "string" } }, "required": [ "id", "ticket_number", "status", "course_number", "fired_at" ], "type": "object" }, "type": "array" }, "vat": { "items": { "properties": { "code": { "type": "string" }, "gross": { "type": "string" }, "net": { "type": "string" }, "rate": { "format": "decimal", "type": "string" }, "tax": { "type": "string" } }, "required": [ "code", "rate", "net", "tax", "gross" ], "type": "object" }, "type": "array" } }, "required": [ "check", "lines", "tickets", "payments", "vat" ], "type": "object" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.fnb_check_detail:invoke" ] } ], "summary": "F&B check detail", "tags": [ "fnb" ] } }, "/v1/functions/hospitality.function.fnb_check_detail/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_fnb_check_detail`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_fnb_check_detail", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate F&B check detail (dry-run)", "tags": [ "fnb" ] } }, "/v1/functions/hospitality.function.fnb_open_checks/invoke": { "post": { "description": "An outlet's open checks, oldest first — the till's check list: each check's id and number, order kind, the label of the table it is seated at (null off the floor), covers, when it opened, its `total_due` and `balance_due` with their `currency`, and its owner (`server_id`, and `opened_by`, the principal that opened it), its `business_date` (the hotel date it opened on) and `carried` — true once the night audit has closed that day and the check rode over the roll (the house's `fnb_open_checks_at_roll = carry`). Narrowed to open checks in the store, so the read never ships the outlet's settled history. The target is the outlet. Read-only.", "operationId": "invoke_hospitality_function_fnb_open_checks", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.outlet" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "properties": { "checks": { "items": { "properties": { "balance_due": { "type": "string" }, "business_date": { "format": "date", "type": "string" }, "carried": { "type": "boolean" }, "cleared_at": { "format": "date-time", "type": "string" }, "covers": { "type": "integer" }, "currency": { "type": "string" }, "delivered_at": { "format": "date-time", "type": "string" }, "delivery_status": { "enum": [ "taken", "dispatched", "delivered", "cleared" ], "type": "string" }, "dispatched_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.guest_check" }, "number": { "type": "string" }, "opened_at": { "format": "date-time", "type": "string" }, "order_kind": { "enum": [ "dine_in", "takeaway", "room_service", "delivery" ], "type": "string" }, "owner": { "properties": { "opened_by": { "type": "string" }, "server_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "required": [ "opened_by" ], "type": "object" }, "promised_at": { "format": "date-time", "type": "string" }, "room": { "type": "string" }, "table_label": { "type": "string" }, "total_due": { "type": "string" } }, "required": [ "id", "number", "order_kind", "opened_at", "carried", "owner" ], "type": "object" }, "type": "array" }, "outlet_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.outlet" } }, "required": [ "outlet_id", "checks" ], "type": "object" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.fnb_open_checks:invoke" ] } ], "summary": "F&B open checks", "tags": [ "revenue" ] } }, "/v1/functions/hospitality.function.fnb_open_checks/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_fnb_open_checks`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_fnb_open_checks", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.outlet" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate F&B open checks (dry-run)", "tags": [ "revenue" ] } }, "/v1/functions/hospitality.function.fnb_outlet_menu/invoke": { "post": { "description": "An outlet's active menus as the till draws them — a menu's sections in order, each section's orderable items (active, and orderable on their own: a modifier-only item has no key) in the order the section places them, and per item its names, its EU-14 `allergens` (null = not yet declared, which the till treats as unknown), its class's `revenue_category` and the course it rings in, its active variants with the `price` in force now for this outlet, `order_kind` and `daypart` on the house's hotel date — the most specific row, as `add_check_line` resolves it; null when no row is in force or two tie, which the till would refuse to ring — and its modifier groups at the bounds this item asks for (`min_select` / `max_select`: the item's own override on the link, else the group's), each option with its price (its own, else the price in force of the variant it adds; null for an instruction that adds nothing) and the `variant_id` it adds. A `daypart` that is a meal (breakfast, brunch, lunch, dinner, late_night) and that the outlet has food for — a menu of its own, or an all-day one — keeps that and the menus that are no meal (all-day, drinks, dessert, room service); any other `daypart` keeps every active menu, so a house running its dinner menu at lunch keeps its keys. `currency` is the house's. Prices are decimal strings. The target is the outlet, so a house-bound bearer (a desk, a till) reads its own house's only. Read-only.", "operationId": "invoke_hospitality_function_fnb_outlet_menu", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "daypart": { "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "title": "Meal period the menus and prices are for (absent = every active menu)", "type": "string" }, "order_kind": { "enum": [ "dine_in", "takeaway", "room_service", "delivery" ], "title": "Order kind the prices are for (absent = rows naming no order kind)", "type": "string" } }, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.outlet" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "properties": { "business_date": { "format": "date", "type": "string" }, "currency": { "type": "string" }, "menus": { "items": { "properties": { "daypart": { "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "type": "string" }, "id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.menu" }, "name": { "type": "string" }, "sections": { "items": { "properties": { "id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.menu_section" }, "items": { "items": { "properties": { "allergens": { "items": { "enum": [ "gluten", "crustaceans", "eggs", "fish", "peanuts", "soybeans", "milk", "nuts", "celery", "mustard", "sesame", "sulphites", "lupin", "molluscs" ], "type": "string" }, "type": "array" }, "code": { "type": "string" }, "course_default": { "type": "integer" }, "description": { "type": "string" }, "id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.menu_item" }, "modifier_groups": { "items": { "properties": { "code": { "type": "string" }, "id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.modifier_group" }, "max_select": { "type": "integer" }, "min_select": { "type": "integer" }, "name": { "type": "string" }, "options": { "items": { "properties": { "id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.modifier_option" }, "is_default": { "type": "boolean" }, "name": { "type": "string" }, "price": { "type": "string" }, "variant_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.menu_item_variant" } }, "required": [ "id", "name", "is_default" ], "type": "object" }, "type": "array" } }, "required": [ "id", "code", "name", "min_select", "options" ], "type": "object" }, "type": "array" }, "name": { "type": "string" }, "revenue_category": { "enum": [ "food", "non_alcoholic_beverage", "alcoholic_beverage", "other" ], "type": "string" }, "short_name": { "type": "string" }, "variants": { "items": { "properties": { "id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.menu_item_variant" }, "is_default": { "type": "boolean" }, "measure": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "string" } }, "required": [ "id", "name", "is_default" ], "type": "object" }, "type": "array" } }, "required": [ "id", "code", "name", "variants", "modifier_groups" ], "type": "object" }, "type": "array" }, "name": { "type": "string" } }, "required": [ "id", "name", "items" ], "type": "object" }, "type": "array" } }, "required": [ "id", "name", "daypart", "sections" ], "type": "object" }, "type": "array" }, "outlet": { "properties": { "code": { "type": "string" }, "id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "name": { "type": "string" } }, "required": [ "id" ], "type": "object" } }, "required": [ "outlet", "business_date", "menus" ], "type": "object" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.fnb_outlet_menu:invoke" ] } ], "summary": "F&B outlet menu", "tags": [ "revenue" ] } }, "/v1/functions/hospitality.function.fnb_outlet_menu/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_fnb_outlet_menu`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_fnb_outlet_menu", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "daypart": { "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "title": "Meal period the menus and prices are for (absent = every active menu)", "type": "string" }, "order_kind": { "enum": [ "dine_in", "takeaway", "room_service", "delivery" ], "title": "Order kind the prices are for (absent = rows naming no order kind)", "type": "string" } }, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.outlet" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate F&B outlet menu (dry-run)", "tags": [ "revenue" ] } }, "/v1/functions/hospitality.function.fnb_receipt/invoke": { "post": { "description": "A settled check's receipt as it was issued — the document's own snapshot, never re-read from the check: its `number` (`R-{outlet}-{000001}`) and `series`, the check it was issued for and that check's number, outlet, order kind, table, covers and server, the business date, the time of supply (`settled_at`) and `issued_at`; the totals (`subtotal`, `tax_total`, `total_due`, `paid_total`, `tip_total`, `change_total`, strings in `currency`); `vat` per rate (code, rate, net, tax, gross — VAT Notice 700 §16.6.1); the printed `lines` (description, quantity, unit price, line total, `modifier`, `comped`); the `payments` (tender, amount, tip, cash tendered and change; a room charge's room and the name of the guest who signed — never card data); the supplier (`supplier_name`, and `issuer`: legal name, address lines, VAT number and scheme); and `content_hash` / `previous_hash`, its place on the property's document chain. What the till previews and the printer renders. The target is the receipt, so a house-bound bearer reads its own house's — and a till its own outlet's — only. Read-only.", "operationId": "invoke_hospitality_function_fnb_receipt", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.check_receipt" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "properties": { "business_date": { "format": "date", "type": "string" }, "change_total": { "type": "string" }, "check_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.guest_check" }, "check_number": { "type": "string" }, "content_hash": { "type": "string" }, "covers": { "type": "integer" }, "currency": { "type": "string" }, "id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.check_receipt" }, "issued_at": { "format": "date-time", "type": "string" }, "issuer": { "properties": { "address_lines": { "items": { "type": "string" }, "type": "array" }, "legal_name": { "type": "string" }, "tax_registration_number": { "type": "string" }, "tax_registration_scheme": { "type": "string" } }, "required": [ "legal_name", "address_lines", "tax_registration_scheme" ], "type": "object" }, "lines": { "items": { "properties": { "comped": { "type": "boolean" }, "description": { "type": "string" }, "line_total": { "type": "string" }, "modifier": { "type": "boolean" }, "quantity": { "type": "integer" }, "unit_price": { "type": "string" } }, "required": [ "description", "quantity", "unit_price", "line_total", "modifier", "comped" ], "type": "object" }, "type": "array" }, "number": { "type": "string" }, "order_kind": { "enum": [ "dine_in", "takeaway", "room_service", "delivery" ], "type": "string" }, "outlet_name": { "type": "string" }, "paid_total": { "type": "string" }, "payments": { "items": { "properties": { "amount": { "type": "string" }, "change_given": { "type": "string" }, "guest_name": { "type": "string" }, "room_number": { "type": "string" }, "tender": { "enum": [ "room_charge", "cash", "card", "comp", "external", "charge_to_key" ], "type": "string" }, "tendered": { "type": "string" }, "tip": { "type": "string" } }, "required": [ "tender", "amount", "tip" ], "type": "object" }, "type": "array" }, "previous_hash": { "type": "string" }, "sequence_value": { "type": "integer" }, "series": { "type": "string" }, "server_name": { "type": "string" }, "settled_at": { "format": "date-time", "type": "string" }, "simplified": { "type": "boolean" }, "subtotal": { "type": "string" }, "supplier_name": { "type": "string" }, "table_label": { "type": "string" }, "tax_total": { "type": "string" }, "time_of_supply": { "type": "string" }, "tip_total": { "type": "string" }, "total_due": { "type": "string" }, "vat": { "items": { "properties": { "code": { "type": "string" }, "gross": { "type": "string" }, "net": { "type": "string" }, "rate": { "format": "decimal", "type": "string" }, "tax": { "type": "string" } }, "required": [ "code", "rate", "net", "tax", "gross" ], "type": "object" }, "type": "array" } }, "required": [ "id", "number", "series", "sequence_value", "check_number", "outlet_name", "order_kind", "business_date", "settled_at", "time_of_supply", "issued_at", "currency", "subtotal", "tax_total", "total_due", "paid_total", "tip_total", "change_total", "vat", "lines", "payments", "supplier_name", "simplified", "content_hash" ], "type": "object" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.fnb_receipt:invoke" ] } ], "summary": "F&B receipt", "tags": [ "fnb" ] } }, "/v1/functions/hospitality.function.fnb_receipt/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_fnb_receipt`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_fnb_receipt", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.check_receipt" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate F&B receipt (dry-run)", "tags": [ "fnb" ] } }, "/v1/functions/hospitality.function.fnb_room_lookup/invoke": { "post": { "description": "The in-house stays a room charge can post to — OHIP's in-house search by room or surname, at the target property. `query` is a room number (an exact match, case-insensitive) or at least three letters of the guest's surname (a prefix) — Simphony's restricted posting: a shorter query matches room numbers only, and an empty one is refused, so the read never lists the house. At most ten stays come back (`truncated` says when there were more). Per in-house stay: how it matched (`matched_by`: `room` or `surname`), its reservation and confirmation number, the room it is in, the guest (`guest_id`, `guest_name`) and the stay's open guest folios with their number and window; on a room match also `sharers` — the other guests in house in that room, each with their `guest_id`, name and reservation (each signs on their own booking), empty on a surname match. And the stay's posting rules, so the till warns before the tender is chosen: `no_post` (the desk's set_posting_rules — a room charge is refused) and `credit_available` — the greater of the stay's credit limit and its live card holds, less its bills' balance and the room still due for the nights to come (a money; null when no credit rule applies: no limit and no hold). Names only, never contact details. Ordered by room, then guest. Guest names are personal data: a reader not cleared for them gets the rows without them. Read-only.", "operationId": "invoke_hospitality_function_fnb_room_lookup", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "query": { "title": "Room number or surname prefix", "type": "string" } }, "required": [ "query" ], "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "properties": { "property_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.property" }, "query": { "type": "string" }, "stays": { "items": { "properties": { "confirmation_number": { "type": "string" }, "credit_available": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "folios": { "items": { "properties": { "folio_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.folio" }, "number": { "type": "string" }, "window_number": { "type": "integer" } }, "required": [ "folio_id" ], "type": "object" }, "type": "array" }, "guest_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.person" }, "guest_name": { "type": "string" }, "matched_by": { "enum": [ "room", "surname" ], "type": "string" }, "no_post": { "type": "boolean" }, "reservation_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "room_number": { "type": "string" }, "sharers": { "items": { "properties": { "guest_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.person" }, "guest_name": { "type": "string" }, "reservation_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation" } }, "required": [ "guest_id", "reservation_id" ], "type": "object" }, "type": "array" }, "stay_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.stay" } }, "required": [ "matched_by", "reservation_id", "stay_id", "sharers", "folios", "no_post" ], "type": "object" }, "type": "array" }, "truncated": { "type": "boolean" } }, "required": [ "property_id", "query", "truncated", "stays" ], "type": "object" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.fnb_room_lookup:invoke" ] } ], "summary": "F&B room lookup", "tags": [ "organization" ] } }, "/v1/functions/hospitality.function.fnb_room_lookup/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_fnb_room_lookup`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_fnb_room_lookup", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "query": { "title": "Room number or surname prefix", "type": "string" } }, "required": [ "query" ], "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate F&B room lookup (dry-run)", "tags": [ "organization" ] } }, "/v1/functions/hospitality.function.fnb_room_service_board/invoke": { "post": { "description": "The target outlet's in-room dining orders still on the dispatch sheet — every room_service check whose `delivery_status` is not yet `cleared`, a settled one whose tray is still upstairs included — ordered by `promised_at` (then by when it opened). `checks`, per order: the check (`id`) and its number and status (open or settled), daypart, covers, the room, the stay and its guests' names, when it opened and was promised, where it is (`delivery_status`, `dispatched_at`, `delivered_at`, the `runner_id` and the `conveyance`), `late` (promised and passed, not yet delivered), and its `total_due` / `balance_due` in `currency`. Narrowed in the store to the orders on the sheet, so the board never ships the cleared history. The target is the outlet, so a till reads its own outlet's board only. Read-only.", "operationId": "invoke_hospitality_function_fnb_room_service_board", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.outlet" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "properties": { "checks": { "items": { "properties": { "balance_due": { "type": "string" }, "conveyance": { "enum": [ "tray", "trolley" ], "type": "string" }, "covers": { "type": "integer" }, "currency": { "type": "string" }, "daypart": { "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "type": "string" }, "delivered_at": { "format": "date-time", "type": "string" }, "delivery_status": { "enum": [ "taken", "dispatched", "delivered", "cleared" ], "type": "string" }, "dispatched_at": { "format": "date-time", "type": "string" }, "guest_names": { "items": { "type": "string" }, "type": "array" }, "id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.guest_check" }, "late": { "type": "boolean" }, "number": { "type": "string" }, "opened_at": { "format": "date-time", "type": "string" }, "promised_at": { "format": "date-time", "type": "string" }, "room": { "type": "string" }, "runner_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "status": { "enum": [ "open", "settled" ], "type": "string" }, "stay_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.stay" }, "total_due": { "type": "string" } }, "required": [ "id", "number", "status", "guest_names", "opened_at", "delivery_status", "late" ], "type": "object" }, "type": "array" }, "outlet_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.outlet" } }, "required": [ "outlet_id", "checks" ], "type": "object" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.fnb_room_service_board:invoke" ] } ], "summary": "F&B room-service board", "tags": [ "revenue" ] } }, "/v1/functions/hospitality.function.fnb_room_service_board/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_fnb_room_service_board`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_fnb_room_service_board", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.outlet" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate F&B room-service board (dry-run)", "tags": [ "revenue" ] } }, "/v1/functions/hospitality.function.hotel_date/invoke": { "post": { "description": "The property's today as the kernel dates a posting, a no-show, a postponement or a report made now — its hotel date: the business date it has open (`open_business_date`) once that day was opened, else its local calendar day. So at 01:00 with yesterday still open the answer is yesterday, and after an early night audit that rolled tomorrow open it is tomorrow. With it `time_zone`, the IANA zone that calendar is read in (absent when the property names none the kernel can read; the calendar is then UTC's), and `business_date_open`: true when the date is a business date opened and not yet closed by `run_night_audit` — it holds until the audit rolls it — and false when no day is open and the date is the calendar's, which moves at the house's midnight. A client reads this rather than computing the fallback with its own clock. Read-only.", "operationId": "invoke_hospitality_function_hotel_date", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "properties": { "business_date_open": { "type": "boolean" }, "hotel_date": { "format": "date", "type": "string" }, "property_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.property" }, "time_zone": { "type": "string" } }, "required": [ "property_id", "hotel_date", "business_date_open" ], "type": "object" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.hotel_date:invoke" ] } ], "summary": "Hotel date", "tags": [ "organization" ] } }, "/v1/functions/hospitality.function.hotel_date/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_hotel_date`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_hotel_date", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Hotel date (dry-run)", "tags": [ "organization" ] } }, "/v1/functions/hospitality.function.housekeeping_pacing/invoke": { "post": { "description": "The housekeeping pacing report for one property and one business date (hubOS's productivity report, counted in OPERA's housekeeping credits). Per attendant: their shift's credit target and the share of it completed; credits assigned, completed, in progress and pending (pending or blocked) with their share of the assigned; rooms assigned, cleaned and on do-not-disturb; cleaning time (`completed_at − started_at` of each complete task), transition time (the gaps between one task's completion and the next start), and the deviation of cleaning time from the tasks' standard minutes, over the tasks that have both; and the average inspection score their cleaning received. A summary for the house: the same credits (plus credits on tasks nobody holds, and a count of unpriced tasks), rooms on the board / assigned / cleaned / pending / inspected / on do-not-disturb, and the times. Skipped tasks count nowhere. Credits and standard minutes are what each task was minted with from the house's credit rules (`set_housekeeping_credit_rule`); targets are set at clock-in or with `set_shift_credit_target`. Computed on read. Read-only.", "operationId": "invoke_hospitality_function_housekeeping_pacing", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "The business date; omit for the floor's today — the house's local calendar day, the day its housekeeping sheet is dated by (not the hotel date, which stays on yesterday until the audit)", "type": "string" } }, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "properties": { "attendants": { "items": { "properties": { "cleaning_seconds": { "type": "integer" }, "completed_percent": { "format": "decimal", "type": "string" }, "contracted_weekly_hours": { "format": "decimal", "type": "string" }, "credit_target": { "format": "decimal", "type": "string" }, "credits_assigned": { "format": "decimal", "type": "string" }, "credits_completed": { "format": "decimal", "type": "string" }, "credits_in_progress": { "format": "decimal", "type": "string" }, "credits_pending": { "format": "decimal", "type": "string" }, "deviation_seconds": { "type": "integer" }, "in_progress_percent": { "format": "decimal", "type": "string" }, "inspection_rating_average": { "format": "decimal", "type": "string" }, "inspections": { "type": "integer" }, "pending_percent": { "format": "decimal", "type": "string" }, "percentage_worked": { "format": "decimal", "type": "string" }, "rooms_assigned": { "type": "integer" }, "rooms_cleaned": { "type": "integer" }, "rooms_dnd": { "type": "integer" }, "self_rating_average": { "format": "decimal", "type": "string" }, "self_ratings": { "type": "integer" }, "staff_member_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "standard_seconds": { "type": "integer" }, "target_percent": { "format": "decimal", "type": "string" }, "time_worked_seconds": { "type": "integer" }, "transition_seconds": { "type": "integer" } }, "required": [ "staff_member_id", "credits_assigned", "credits_completed", "credits_in_progress", "credits_pending", "rooms_assigned", "rooms_cleaned", "rooms_dnd", "cleaning_seconds", "transition_seconds", "standard_seconds", "deviation_seconds", "inspections", "self_ratings" ], "type": "object" }, "type": "array" }, "business_date": { "format": "date", "type": "string" }, "property_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.property" }, "summary": { "properties": { "cleaning_seconds": { "type": "integer" }, "completed_percent": { "format": "decimal", "type": "string" }, "credits_assigned": { "format": "decimal", "type": "string" }, "credits_completed": { "format": "decimal", "type": "string" }, "credits_in_progress": { "format": "decimal", "type": "string" }, "credits_pending": { "format": "decimal", "type": "string" }, "credits_unassigned": { "format": "decimal", "type": "string" }, "deviation_seconds": { "type": "integer" }, "in_progress_percent": { "format": "decimal", "type": "string" }, "pending_percent": { "format": "decimal", "type": "string" }, "rooms": { "type": "integer" }, "rooms_assigned": { "type": "integer" }, "rooms_cleaned": { "type": "integer" }, "rooms_dnd": { "type": "integer" }, "rooms_inspected": { "type": "integer" }, "rooms_pending": { "type": "integer" }, "standard_seconds": { "type": "integer" }, "tasks_unpriced": { "type": "integer" }, "transition_seconds": { "type": "integer" } }, "required": [ "credits_assigned", "credits_completed", "credits_in_progress", "credits_pending", "credits_unassigned", "tasks_unpriced", "rooms", "rooms_assigned", "rooms_cleaned", "rooms_pending", "rooms_inspected", "rooms_dnd", "cleaning_seconds", "transition_seconds", "standard_seconds", "deviation_seconds" ], "type": "object" } }, "required": [ "property_id", "business_date", "summary", "attendants" ], "type": "object" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.housekeeping_pacing:invoke" ] } ], "summary": "Housekeeping pacing", "tags": [ "organization" ] } }, "/v1/functions/hospitality.function.housekeeping_pacing/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_housekeeping_pacing`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_housekeeping_pacing", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "The business date; omit for the floor's today — the house's local calendar day, the day its housekeeping sheet is dated by (not the hotel date, which stays on yesterday until the audit)", "type": "string" } }, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Housekeeping pacing (dry-run)", "tags": [ "organization" ] } }, "/v1/functions/hospitality.function.housekeeping_requests/invoke": { "post": { "description": "The house's open housekeeping tasks that carry a due time — hubOS's service requests with a delivery time — each with its urgency at the kernel's now: `overdue` once `due_at` has passed, `soon` within the next `soon_minutes` (30), `scheduled` beyond. Open is pending, in progress or blocked. The queue is every open request due by the end of the day after `business_date` (the house's hotel date when not named), however long ago its time passed — an open request stays in front of the shift until it is closed — so last night's late request, one still open from the day before, and tomorrow morning's early one are all on today's read; a request due later than tomorrow joins it the day before. That is the floor's read, `horizon` `shift`; the desk's planning read, `horizon` `all`, lists every open request with a due time whatever its day, so a request re-timed to next week stays in the room until then. Soonest first; each row carries the task's status, type, priority, `requested_by`, why a blocked one waits (`block_reason`), when the work began (`started_at`), its business date, its room or area and the person or group that holds it — a whole line for a request on another day's sheet. `as_of` is the instant the urgencies were judged at — a client counting down between reads applies `soon_minutes` to it. The urgency is never stored: it changes with the clock, not with a write. Read-only.", "operationId": "invoke_hospitality_function_housekeeping_requests", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "The day whose next day ends the queue (defaults to the house's hotel date)", "type": "string" }, "horizon": { "enum": [ "shift", "all" ], "title": "`shift` (the default): open requests due by the end of the day after `business_date`; `all`: every open request with a due time, whatever its day — the desk's planning read", "type": "string" } }, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "properties": { "as_of": { "format": "date-time", "type": "string" }, "property_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.property" }, "requests": { "items": { "properties": { "area_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.public_area" }, "assignee_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "block_reason": { "enum": [ "do_not_disturb", "guest_in_room", "access_refused", "maintenance_required", "other" ], "type": "string" }, "business_date": { "format": "date", "type": "string" }, "due_at": { "format": "date-time", "type": "string" }, "group_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.worker_group" }, "priority": { "enum": [ "low", "normal", "high", "urgent" ], "type": "string" }, "requested_by": { "enum": [ "guest", "desk", "floor", "pms", "automation" ], "type": "string" }, "room_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.room" }, "started_at": { "format": "date-time", "type": "string" }, "status": { "enum": [ "pending", "in_progress", "blocked", "complete", "skipped" ], "type": "string" }, "task_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.housekeeping_task" }, "task_type": { "enum": [ "stayover", "departure", "vacant_pickup", "deep_clean", "turndown", "inspection", "public_area_clean", "public_area_inspection", "minibar", "laundry" ], "type": "string" }, "urgency": { "enum": [ "overdue", "soon", "scheduled" ], "type": "string" } }, "required": [ "task_id", "due_at", "urgency", "status", "task_type", "priority" ], "type": "object" }, "type": "array" }, "soon_minutes": { "type": "integer" } }, "required": [ "property_id", "as_of", "soon_minutes", "requests" ], "type": "object" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.housekeeping_requests:invoke" ] } ], "summary": "Housekeeping requests", "tags": [ "organization" ] } }, "/v1/functions/hospitality.function.housekeeping_requests/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_housekeeping_requests`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_housekeeping_requests", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "The day whose next day ends the queue (defaults to the house's hotel date)", "type": "string" }, "horizon": { "enum": [ "shift", "all" ], "title": "`shift` (the default): open requests due by the end of the day after `business_date`; `all`: every open request with a due time, whatever its day — the desk's planning read", "type": "string" } }, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Housekeeping requests (dry-run)", "tags": [ "organization" ] } }, "/v1/functions/hospitality.function.inspect_federated_output_privacy/invoke": { "post": { "description": "Return disclosure-control metadata for a published federated output: suppression reasons, privacy guarantee, budget spend, noise parameters, confidence intervals, and publication evidence. The return intentionally excludes metric_values and artifact bodies.", "operationId": "invoke_hospitality_function_inspect_federated_output_privacy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "output_id": { "format": "uuid", "title": "Federated output id", "type": "string", "x-aerandil-references": "hospitality.federated_output" } }, "required": [ "output_id" ], "type": "object" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "properties": { "confidence_intervals": {}, "noise_parameters": {}, "output_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.federated_output" }, "privacy_budget_spend": {}, "privacy_guarantee_summary": {}, "publication_evidence": {}, "published_at": { "format": "date-time", "type": "string" }, "review_gate_id": { "type": "string" }, "status": { "enum": [ "draft", "reviewing", "published", "revoked", "quarantined", "expired" ], "type": "string" }, "suppression_applied": { "type": "boolean" }, "suppression_reasons": { "items": { "enum": [ "minimum_tenants_not_met", "minimum_properties_not_met", "minimum_subjects_not_met", "max_contributor_share_exceeded", "privacy_budget_exhausted", "high_variance", "data_quality_mismatch", "legal_basis_missing", "participant_withdrawal", "reviewer_blocked", "security_incident" ], "type": "string" }, "type": "array" } }, "required": [ "output_id", "status", "suppression_applied", "suppression_reasons", "privacy_guarantee_summary", "privacy_budget_spend" ], "type": "object" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.inspect_federated_output_privacy:invoke" ] } ], "summary": "Inspect federated output privacy", "tags": [ "hospitality" ] } }, "/v1/functions/hospitality.function.inspect_federated_output_privacy/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_inspect_federated_output_privacy`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_inspect_federated_output_privacy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "output_id": { "format": "uuid", "title": "Federated output id", "type": "string", "x-aerandil-references": "hospitality.federated_output" } }, "required": [ "output_id" ], "type": "object" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Inspect federated output privacy (dry-run)", "tags": [ "hospitality" ] } }, "/v1/functions/hospitality.function.invoices_due/invoke": { "post": { "description": "The company bills a property still owes a document, soonest deadline first: guest folios direct-billed to a company's A/R account (open until their invoice seals them; counted from the transfer) and closed folios of reservations booked for a company (counted from the close), with no invoice yet. The deadline is the property's `billing_identity.invoice_issue_deadline_days` — 30 when unset, the UK rule (VAT Notice 700 §16.2.3); a German house sets about six months (§14 Abs. 2 UStG). Leisure guests' bills are not listed: a VAT invoice is owed to a VAT-registered customer, not to every guest (Notice 700 §16.2.1). Each row carries the folio, the company, why it is listed, the supply date, the deadline and the days left (negative once passed). Read-only.", "operationId": "invoke_hospitality_function_invoices_due", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "as_of": { "format": "date", "title": "The day to count the days left from; omit for the house's today — its hotel date, the business date it has open, else its local calendar day", "type": "string" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "property_id" ], "type": "object" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "items": { "properties": { "balance": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "basis": { "enum": [ "direct_bill", "company_booking" ], "type": "string" }, "company_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.company" }, "company_name": { "type": "string" }, "days_left": { "type": "integer" }, "deadline": { "format": "date", "type": "string" }, "deadline_days": { "type": "integer" }, "folio_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.folio" }, "folio_number": { "type": "string" }, "supply_date": { "format": "date", "type": "string" } }, "required": [ "folio_id", "folio_number", "company_id", "basis", "supply_date", "deadline", "deadline_days", "days_left" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.invoices_due:invoke" ] } ], "summary": "Invoices due", "tags": [ "hospitality" ] } }, "/v1/functions/hospitality.function.invoices_due/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_invoices_due`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_invoices_due", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "as_of": { "format": "date", "title": "The day to count the days left from; omit for the house's today — its hotel date, the business date it has open, else its local calendar day", "type": "string" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "property_id" ], "type": "object" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Invoices due (dry-run)", "tags": [ "hospitality" ] } }, "/v1/functions/hospitality.function.list_federated_outputs_for_participant/invoke": { "post": { "description": "Return published federated outputs a participation may consume. The function walks participation → program → definition → run → output through the ontology graph, applies the participation's output_access_level, and hides non-published outputs. It returns aggregate output metadata only — never local contribution payloads or tenant-level source rows.", "operationId": "invoke_hospitality_function_list_federated_outputs_for_participant", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "participation_id": { "format": "uuid", "title": "Federated participation id", "type": "string", "x-aerandil-references": "hospitality.federated_participation" } }, "required": [ "participation_id" ], "type": "object" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "items": { "properties": { "applicability_statement": { "type": "string" }, "artifact_reference": { "type": "string" }, "downstream_use_restrictions": { "type": "string" }, "output_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.federated_output" }, "output_kind": { "enum": [ "benchmark_report", "calibration_curve", "aggregate_metric", "model_artifact", "signal_package", "governance_card" ], "type": "string" }, "output_schema_version": { "type": "string" }, "published_at": { "format": "date-time", "type": "string" }, "published_to_scope": { "enum": [ "program_owner", "participants", "public_aggregate", "specific_recipients" ], "type": "string" }, "run_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.federated_run" }, "suppression_applied": { "type": "boolean" }, "suppression_reasons": { "items": { "enum": [ "minimum_tenants_not_met", "minimum_properties_not_met", "minimum_subjects_not_met", "max_contributor_share_exceeded", "privacy_budget_exhausted", "high_variance", "data_quality_mismatch", "legal_basis_missing", "participant_withdrawal", "reviewer_blocked", "security_incident" ], "type": "string" }, "type": "array" } }, "required": [ "output_id", "run_id", "output_kind", "output_schema_version", "published_to_scope", "suppression_applied", "suppression_reasons", "applicability_statement", "downstream_use_restrictions" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.list_federated_outputs_for_participant:invoke" ] } ], "summary": "List federated outputs for participant", "tags": [ "hospitality" ] } }, "/v1/functions/hospitality.function.list_federated_outputs_for_participant/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_list_federated_outputs_for_participant`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_list_federated_outputs_for_participant", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "participation_id": { "format": "uuid", "title": "Federated participation id", "type": "string", "x-aerandil-references": "hospitality.federated_participation" } }, "required": [ "participation_id" ], "type": "object" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate List federated outputs for participant (dry-run)", "tags": [ "hospitality" ] } }, "/v1/functions/hospitality.function.open_shift_for_staff/invoke": { "post": { "description": "A staff member's open shift — the one `clock_in` opened and `clock_out` has not closed — or none (`shift` absent). The shift's id (the target `set_shift_credit_target` and `clock_out` take), its house, the business date its hours will report under (the property-local day of its start, as clock-out stamps it), its scheduled and actual start and scheduled end, and the housekeeping credit target the pacing report counts the attendant against. The times and the target are staff data: a reader without that clearance gets the shift without them. Read-only.", "operationId": "invoke_hospitality_function_open_shift_for_staff", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "properties": { "shift": { "properties": { "actual_start": { "format": "date-time", "type": "string" }, "business_date": { "format": "date", "type": "string" }, "credit_target": { "format": "decimal", "type": "string" }, "id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.staff_shift" }, "property_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.property" }, "scheduled_end": { "format": "date-time", "type": "string" }, "scheduled_start": { "format": "date-time", "type": "string" } }, "required": [ "id" ], "type": "object" }, "staff_member_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "required": [ "staff_member_id" ], "type": "object" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.open_shift_for_staff:invoke" ] } ], "summary": "Open shift for staff", "tags": [ "people" ] } }, "/v1/functions/hospitality.function.open_shift_for_staff/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_open_shift_for_staff`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_open_shift_for_staff", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Open shift for staff (dry-run)", "tags": [ "people" ] } }, "/v1/functions/hospitality.function.plan_hold_top_up/invoke": { "post": { "description": "What an in-house stay's pending card holds cover against its bill, and what the night audit's top-up would do about it now: `held` (the stay's live holds), `posted` (the balance of the bills they sit on), `incidental` (the allowance of the incidental-hold rule the booking matches, for the nights still to come — at least one), and OPERA's top-up, `excess` = posted − held + incidental. `action` is `top_up` (a second hold of `amount`, by the house's `set_hold_top_up` rule above its threshold, or by `set_credit_limit_overage = hold` once the bill reached what is held), `charge` (`credit_limit_overage = charge` and the bill has reached what is held: `capture` taken from the holds and `amount` held afresh), `refused` (`refusal`: the house's `max_per_stay` reached, or the money in more than one currency) or `none`; `reason` is the desk's sentence. Also the rule (`policy_code`, `match_reason`), the house's settings, the stay's top-ups so far, its last recorded refusal and any attempt the card rail opened and has not recorded. The card rail acts on this after each night audit and on the desk's Top up now; nothing is held by reading it. Read-only.", "operationId": "invoke_hospitality_function_plan_hold_top_up", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "on_demand": { "title": "The desk's Top up now: any excess is due, whatever the house's rule and threshold (never past its max_per_stay)", "type": "boolean" } }, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "properties": { "action": { "enum": [ "none", "top_up", "charge", "refused" ], "type": "string" }, "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "capture": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "credit_limit_overage": { "enum": [ "off", "hold", "charge" ], "type": "string" }, "excess": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "folio_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.folio" }, "held": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "hold_payment_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.payment" }, "holds": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.payment" }, "type": "array" }, "incidental": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "last_refusal": { "enum": [ "card_declined", "insufficient_funds", "authentication_required", "no_consent", "no_card", "max_reached", "other_currency", "processor_refused", "attempt_abandoned" ], "type": "string" }, "last_refusal_detail": { "type": "string" }, "last_refused_at": { "format": "date-time", "type": "string" }, "match_reason": { "type": "string" }, "max_per_stay": { "type": "integer" }, "nights_left": { "type": "integer" }, "open_attempt": { "type": "string" }, "policy_code": { "type": "string" }, "posted": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "reason": { "type": "string" }, "refusal": { "enum": [ "card_declined", "insufficient_funds", "authentication_required", "no_consent", "no_card", "max_reached", "other_currency", "processor_refused", "attempt_abandoned" ], "type": "string" }, "threshold": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "top_up_on": { "type": "boolean" }, "top_ups": { "type": "integer" } }, "required": [ "action", "reason", "top_ups", "max_per_stay", "top_up_on", "credit_limit_overage" ], "type": "object" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.plan_hold_top_up:invoke" ] } ], "summary": "Plan hold top-up", "tags": [ "booking" ] } }, "/v1/functions/hospitality.function.plan_hold_top_up/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_plan_hold_top_up`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_plan_hold_top_up", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "on_demand": { "title": "The desk's Top up now: any excess is due, whatever the house's rule and threshold (never past its max_per_stay)", "type": "boolean" } }, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Plan hold top-up (dry-run)", "tags": [ "booking" ] } }, "/v1/functions/hospitality.function.preview_invoice/invoke": { "post": { "description": "Dry-run `issue_invoice` against a folio: whether it can be issued, what the document would say, and if not, why not — the `INVOICE_BLOCKERS` vocabulary, all of them at once rather than one refusal at a time. Runs the identical decision the action runs, so the two can never disagree about what is wrong. Read-only, and critically it allocates no number: a preview must not consume a value from a series that has to stay dense.", "operationId": "invoke_hospitality_function_preview_invoice", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "recipient_kind": { "enum": [ "person", "company" ], "title": "Preview billing the guest or the company; omit for the default the action would pick", "type": "string" } }, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "properties": { "amount_due": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "amount_paid": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "blockers": { "items": { "type": "string" }, "type": "array" }, "can_issue": { "type": "boolean" }, "currency": { "format": "iso-4217", "type": "string" }, "due_on": { "format": "date", "type": "string" }, "gross_total": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "issuer": {}, "kind": { "type": "string" }, "lines": {}, "net_total": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "recipient": {}, "recipient_id": { "type": "string" }, "recipient_kind": { "type": "string" }, "seals_folio": { "type": "boolean" }, "simplified": { "type": "boolean" }, "supply_from": { "format": "date", "type": "string" }, "supply_to": { "format": "date", "type": "string" }, "tax_summary": {}, "tax_total": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "can_issue", "blockers" ], "type": "object" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.preview_invoice:invoke" ] } ], "summary": "Preview invoice", "tags": [ "finance" ] } }, "/v1/functions/hospitality.function.preview_invoice/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_preview_invoice`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_preview_invoice", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "recipient_kind": { "enum": [ "person", "company" ], "title": "Preview billing the guest or the company; omit for the default the action would pick", "type": "string" } }, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Preview invoice (dry-run)", "tags": [ "finance" ] } }, "/v1/functions/hospitality.function.query_objects/invoke": { "post": { "description": "Query objects of one type, optionally narrowed by conjunctive equality filters, returning up to `limit` summaries ordered by creation time (oldest first). Reads through the caller's authority and any active branch overlay — under a preview it composes the draft's own hypothetical writes, so it is the read-your-writes search surface for agents. Marking-redacted exactly like `get` / `list`: a value the caller cannot read is absent and cannot be filtered on. Each hit is `{id, object_type, properties}` with flat property values. Read-only — emits no edits.", "operationId": "invoke_hospitality_function_query_objects", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "filters": { "title": "Conjunctive equality filters as a JSON object {property_api_name: value}" }, "limit": { "title": "Maximum hits to return (default 50, capped at 200)", "type": "integer" }, "object_type": { "title": "Object-type api name to query", "type": "string" } }, "required": [ "object_type" ], "type": "object" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "items": {}, "type": "array" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.query_objects:invoke" ] } ], "summary": "Query objects", "tags": [ "hospitality" ] } }, "/v1/functions/hospitality.function.query_objects/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_query_objects`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_query_objects", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "filters": { "title": "Conjunctive equality filters as a JSON object {property_api_name: value}" }, "limit": { "title": "Maximum hits to return (default 50, capped at 200)", "type": "integer" }, "object_type": { "title": "Object-type api name to query", "type": "string" } }, "required": [ "object_type" ], "type": "object" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Query objects (dry-run)", "tags": [ "hospitality" ] } }, "/v1/functions/hospitality.function.quote_cancellation_penalty/invoke": { "post": { "description": "Compute the cancellation penalty that would apply if the reservation were cancelled at `cancel_at`. Walks the bound `cancellation_policy` tier ladder against the reservation's arrival and returns the matched tier plus diagnostic context (hours of notice, no-show classification, the policy's non-refundable flag). Read-only — emits no edits.", "operationId": "invoke_hospitality_function_quote_cancellation_penalty", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "cancel_at": { "format": "date-time", "title": "Hypothetical cancellation time", "type": "string" }, "reservation_room_id": { "format": "uuid", "title": "One room of the booking, to quote its part alone", "type": "string", "x-aerandil-references": "hospitality.reservation_room" } }, "required": [ "cancel_at" ], "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "properties": { "arrival_date": { "format": "date", "type": "string" }, "cancel_at": { "format": "date-time", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" }, "effective_penalty": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "expected_total": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "fee_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "fee_due_at": { "format": "date-time", "type": "string" }, "matched_step_index": { "type": "integer" }, "no_show_fee_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "penalty_kind": { "enum": [ "absolute", "percent_of_total", "n_nights" ], "type": "string" }, "policy_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.cancellation_policy" }, "room_penalty": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "policy_id", "currency", "cancel_at", "arrival_date", "matched_step_index" ], "type": "object" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.quote_cancellation_penalty:invoke" ] } ], "summary": "Quote cancellation penalty", "tags": [ "booking" ] } }, "/v1/functions/hospitality.function.quote_cancellation_penalty/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_quote_cancellation_penalty`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_quote_cancellation_penalty", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "cancel_at": { "format": "date-time", "title": "Hypothetical cancellation time", "type": "string" }, "reservation_room_id": { "format": "uuid", "title": "One room of the booking, to quote its part alone", "type": "string", "x-aerandil-references": "hospitality.reservation_room" } }, "required": [ "cancel_at" ], "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Quote cancellation penalty (dry-run)", "tags": [ "booking" ] } }, "/v1/functions/hospitality.function.quote_stay/invoke": { "post": { "description": "The read half of `create_reservation`'s admission gate. For a stay (arrival, departure) at an occupancy (`adults`, the grid's occupancy), one offer per room type and rate plan the property sells — or the one asked for: whether the action would admit it without a `nightly_rate`, the published price of every night and the total, the rooms the availability ledger will still sell and the ceiling it sells to, the stop-sold nights, the stay-length window in force for the arrival, and every blocker in the `STAY_BLOCKERS` vocabulary, each carrying the refusal the action would make for it verbatim. The action refuses with the first blocker, in the order it checks; the quote returns them all, so the two cannot disagree about what is wrong. A room per offer: a multi-room stay is several quotes. Read-only — emits no edits and holds nothing.", "operationId": "invoke_hospitality_function_quote_stay", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "adults": { "title": "Adults — the occupancy the grid is priced at", "type": "integer" }, "arrival_date": { "format": "date", "title": "Arrival date", "type": "string" }, "departure_date": { "format": "date", "title": "Departure date (the arrival date for a day-use slot)", "type": "string" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan; omit for every plan the property sells", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type; omit for every type the property sells", "type": "string", "x-aerandil-references": "hospitality.room_type" } }, "required": [ "property_id", "arrival_date", "departure_date", "adults" ], "type": "object" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "items": { "properties": { "available": { "type": "integer" }, "blockers": { "items": { "properties": { "kind": { "enum": [ "stay_shape", "below_plan_minimum", "above_plan_maximum", "rate_plan_invalid", "unpriced", "currency_mismatch", "closed", "closed_to_arrival", "closed_to_departure", "below_minimum_stay", "above_maximum_stay", "sold_out" ], "type": "string" }, "night": { "format": "date", "type": "string" }, "reason": { "type": "string" } }, "required": [ "kind", "reason" ], "type": "object" }, "type": "array" }, "bookable": { "type": "boolean" }, "currency": { "format": "iso-4217", "type": "string" }, "max_stay": { "type": "integer" }, "min_stay": { "type": "integer" }, "nights": { "items": { "properties": { "ceiling": { "type": "integer" }, "closed": { "type": "boolean" }, "date": { "format": "date", "type": "string" }, "free": { "type": "integer" }, "rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "date", "closed" ], "type": "object" }, "type": "array" }, "rate_plan_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "total": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "room_type_id", "rate_plan_id", "bookable", "blockers", "nights" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.quote_stay:invoke" ] } ], "summary": "Quote stay", "tags": [ "hospitality" ] } }, "/v1/functions/hospitality.function.quote_stay/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_quote_stay`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_quote_stay", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "adults": { "title": "Adults — the occupancy the grid is priced at", "type": "integer" }, "arrival_date": { "format": "date", "title": "Arrival date", "type": "string" }, "departure_date": { "format": "date", "title": "Departure date (the arrival date for a day-use slot)", "type": "string" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "rate_plan_id": { "format": "uuid", "title": "Rate plan; omit for every plan the property sells", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "title": "Room type; omit for every type the property sells", "type": "string", "x-aerandil-references": "hospitality.room_type" } }, "required": [ "property_id", "arrival_date", "departure_date", "adults" ], "type": "object" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Quote stay (dry-run)", "tags": [ "hospitality" ] } }, "/v1/functions/hospitality.function.regret_record/invoke": { "post": { "description": "The regret record, derived. Every shopping session the house kept through `offer_stay` that booked nothing — no reservation linked to it (`reservation_booked_in_session`) booked by `as_of` — as its last offer, OPERA's \"only the last room/rate combination\": the stay, the party, the room type and plan, the rate quoted, the channel, when the shopper last looked, how many offers the session made, and the visitor key the house issued (absent for a reader without `pii.guest` clearance), so a desk can fold one browser's earlier visits into its later booking. Nobody records a regret: the absence of a booking in the session is one. A session whose last offer is within thirty minutes of `as_of` is still in progress and left off. `since` keeps the sessions whose last offer fell at or after it. Read-only — emits no edits.", "operationId": "invoke_hospitality_function_regret_record", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "as_of": { "format": "date-time", "title": "Read the record as it stood at this instant (defaults to now)", "type": "string" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "since": { "format": "date-time", "title": "Sessions whose last offer fell at or after this instant; omit for all", "type": "string" } }, "required": [ "property_id" ], "type": "object" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "items": { "properties": { "adults": { "type": "integer" }, "arrival_date": { "format": "date", "type": "string" }, "departure_date": { "format": "date", "type": "string" }, "nights": { "type": "integer" }, "offered_at": { "format": "date-time", "type": "string" }, "offers": { "type": "integer" }, "quoted_rate": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "rate_plan_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "session_id": { "type": "string" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "type": "string" }, "total": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "visitor_id": { "type": "string" } }, "required": [ "session_id", "offered_at", "arrival_date", "departure_date", "nights", "adults", "room_type_id", "rate_plan_id", "quoted_rate", "total", "source", "offers" ], "type": "object" }, "type": "array" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.regret_record:invoke" ] } ], "summary": "Regret record", "tags": [ "hospitality" ] } }, "/v1/functions/hospitality.function.regret_record/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_regret_record`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_regret_record", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "as_of": { "format": "date-time", "title": "Read the record as it stood at this instant (defaults to now)", "type": "string" }, "property_id": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "since": { "format": "date-time", "title": "Sessions whose last offer fell at or after this instant; omit for all", "type": "string" } }, "required": [ "property_id" ], "type": "object" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Regret record (dry-run)", "tags": [ "hospitality" ] } }, "/v1/functions/hospitality.function.resolve_access_credential/invoke": { "post": { "description": "The name-echo half of tap-to-charge: resolve a tapped card's opaque token to its in-house stay so staff can confirm the guest (\"charging to Sam Altman, room 204 — correct?\") before `post_charge_by_credential` posts anything. Returns the credential, guest display name, room number, stay / folio references, and the credential's spending caps. Fails closed with one generic error for unknown, revoked, expired, and checked-out credentials — a probing caller learns nothing from the failure mode. Read-only — emits no edits.", "operationId": "invoke_hospitality_function_resolve_access_credential", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "token": { "title": "Opaque vendor token read at tap time", "type": "string" } }, "required": [ "token" ], "type": "object" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "properties": { "credential_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.access_credential" }, "daily_cap": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "expires_at": { "format": "date-time", "type": "string" }, "folio_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.folio" }, "guest_name": { "type": "string" }, "kind": { "enum": [ "key_card", "wristband", "mobile_key", "other" ], "type": "string" }, "per_charge_cap": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "room_number": { "type": "string" }, "stay_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.stay" }, "token_hint": { "type": "string" } }, "required": [ "credential_id", "kind", "stay_id", "folio_id" ], "type": "object" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.resolve_access_credential:invoke" ] } ], "summary": "Resolve access credential", "tags": [ "hospitality" ] } }, "/v1/functions/hospitality.function.resolve_access_credential/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_resolve_access_credential`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_resolve_access_credential", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "token": { "title": "Opaque vendor token read at tap time", "type": "string" } }, "required": [ "token" ], "type": "object" } }, "required": [ "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Resolve access credential (dry-run)", "tags": [ "hospitality" ] } }, "/v1/functions/hospitality.function.room_candidates/invoke": { "post": { "description": "The physical rooms of a reservation leg's booked room type, for the leg's stay. Refused once the reservation is past the point of assignment: this is a pre-check-in read, like the move it serves. Per room: its id and number, its floor, housekeeping status and occupancy, any status block the stay's window meets, and two answers. `assignable` is what `assign_room_for_reservation_room` will do: false when another reservation holds the room for an overlapping window (`held_by` names it; a declared share does not count) or it is out of order for the stay. Out of service only warns, and a dirty or occupied room can still be assigned, because the desk plans ahead. `ready` is whether the guest could walk in now: clean or inspected, vacant, and not out of order. Ordered best first: assignable rooms that are ready, then assignable rooms that are not, then the rest, by room number. `has_special_request` is true when the stay carries a request, whether or not this reader may see the text. Read-only.", "operationId": "invoke_hospitality_function_room_candidates", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation_room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "properties": { "arrival_date": { "format": "date", "type": "string" }, "departure_date": { "format": "date", "type": "string" }, "has_special_request": { "type": "boolean" }, "reservation_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "reservation_room_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation_room" }, "room_type_code": { "type": "string" }, "room_type_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "rooms": { "items": { "properties": { "assignable": { "type": "boolean" }, "block": { "enum": [ "out_of_order", "out_of_service" ], "type": "string" }, "floor": { "type": "string" }, "held_by": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "housekeeping_status": { "type": "string" }, "number": { "type": "string" }, "occupancy": { "type": "string" }, "ready": { "type": "boolean" }, "room_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.room" } }, "required": [ "room_id", "assignable", "ready" ], "type": "object" }, "type": "array" } }, "required": [ "reservation_room_id", "reservation_id", "has_special_request", "room_type_id", "arrival_date", "departure_date", "rooms" ], "type": "object" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.room_candidates:invoke" ] } ], "summary": "Room candidates", "tags": [ "booking" ] } }, "/v1/functions/hospitality.function.room_candidates/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_room_candidates`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_room_candidates", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation_room" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Room candidates (dry-run)", "tags": [ "booking" ] } }, "/v1/functions/hospitality.function.rooming_plan/invoke": { "post": { "description": "A room for every arrival on a date that still needs one, as one plan: each unassigned leg of a confirmed, held or modified reservation is placed in the room `room_candidates` would rank first, longest stay first, and no room is used twice. `date` defaults to the house's hotel date. Each of `lines` gives the reservation, the leg (`reservation_room_id`, the target `assign_room_for_reservation_room` takes), the guest, the room (`room_id`, `room_number`) and `ready`, whether the guest could walk in now. `held_back` lists the legs left to a person, with `reason`: `request_to_check` when the stay carries a special request, which has to be read before a room is chosen, and `no_room` when no room of the booked type can take the stay. Nothing is assigned: this is a read, and a line takes effect only when it is put to the assign action. Guest names are personal data: a reader not cleared for them gets the rows without them.", "operationId": "invoke_hospitality_function_rooming_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "date": { "format": "date", "title": "The arrival date to plan; the house's hotel date when omitted", "type": "string" } }, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "properties": { "date": { "format": "date", "type": "string" }, "held_back": { "items": { "properties": { "confirmation_number": { "type": "string" }, "guest_name": { "type": "string" }, "reason": { "enum": [ "request_to_check", "no_room" ], "type": "string" }, "reservation_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "reservation_room_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation_room" }, "room_type_code": { "type": "string" } }, "required": [ "reservation_id", "reservation_room_id", "reason" ], "type": "object" }, "type": "array" }, "lines": { "items": { "properties": { "confirmation_number": { "type": "string" }, "guest_name": { "type": "string" }, "ready": { "type": "boolean" }, "reservation_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "reservation_room_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation_room" }, "room_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.room" }, "room_number": { "type": "string" }, "room_type_code": { "type": "string" } }, "required": [ "reservation_id", "reservation_room_id", "room_id", "ready" ], "type": "object" }, "type": "array" } }, "required": [ "date", "lines", "held_back" ], "type": "object" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.rooming_plan:invoke" ] } ], "summary": "Rooming plan", "tags": [ "organization" ] } }, "/v1/functions/hospitality.function.rooming_plan/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_rooming_plan`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_rooming_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": { "date": { "format": "date", "title": "The arrival date to plan; the house's hotel date when omitted", "type": "string" } }, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Rooming plan (dry-run)", "tags": [ "organization" ] } }, "/v1/functions/hospitality.function.suggest_incidental_hold/invoke": { "post": { "description": "The card hold a check-in should suggest for this reservation, from the property's incidental-hold rule (`set_incidental_hold_policy`): the active rule the reservation matches most specifically in OPERA's precedence (room type, then rate plan, then guarantee, then source, the house default last), applied to the stay's nights (a day-use stay counts one), its persons and its room total — OPERA's nights × Daily Rate, the `expected_total` (else the booked nights) plus the room taxes charged on top (`room_taxes`). Returns the amount, the rule (id, code, basis, allowance), what it matched on and why (`matched_on`, `match_reason`) and the inputs, or — with no amount — the reason there is nothing to suggest. The desk pre-fills its hold field with the amount and names the rule; nothing is held until a person confirms. Read-only.", "operationId": "invoke_hospitality_function_suggest_incidental_hold", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "Envelope returned by the Aerandil function engine. `correlation_id` is the per-invocation id for trace stitching; `return_value` is the typed value the function computed (shape declared by the function's `return_type`).", "properties": { "correlation_id": { "description": "Per-invocation correlation id; appears on log/trace records this function emitted.", "format": "uuid", "type": "string" }, "return_value": { "properties": { "allowance": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "basis": { "enum": [ "per_night", "room_and_per_night", "room_plus_flat", "flat", "room", "room_and_per_person_night", "per_person_night", "room_plus_percent" ], "type": "string" }, "match_reason": { "type": "string" }, "matched_on": { "items": { "type": "string" }, "type": "array" }, "nights": { "type": "integer" }, "persons": { "type": "integer" }, "policy_code": { "type": "string" }, "policy_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.incidental_hold_policy" }, "reason": { "type": "string" }, "room_taxes": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "room_total": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "nights" ], "type": "object" } }, "required": [ "correlation_id", "return_value" ], "title": "InvokeFunctionResponse", "type": "object" } } }, "description": "Function invoked. The body carries the typed `return_value` shaped by the function's declared `return_type`.", "headers": { "Cache-Control": { "description": "Always `no-store` — function results are time-sensitive and never cacheable.", "schema": { "type": "string" } } } }, "404": { "description": "Function or target object not found." }, "422": { "description": "Parameter validation or domain-rule violation." } }, "security": [ { "aerandil_oauth": [ "functions:invoke" ] }, { "aerandil_oauth": [ "functions:hospitality.function.suggest_incidental_hold:invoke" ] } ], "summary": "Suggest incidental hold", "tags": [ "booking" ] } }, "/v1/functions/hospitality.function.suggest_incidental_hold/validate": { "post": { "description": "Dry-run of `invoke_hospitality_function_suggest_incidental_hold`'s parameter checks. No handler dispatch, no store reads — just parameter shape, target presence, target type, unknown-parameter rejection.", "operationId": "validate_function_hospitality_function_suggest_incidental_hold", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "params": { "additionalProperties": false, "properties": {}, "type": "object" }, "target": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" } }, "required": [ "object_type", "id" ], "type": "object" } }, "required": [ "target", "params" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errors": { "description": "Function-level errors not tied to a single parameter (missing target, target type mismatch, unknown parameter names). Absent when empty.", "items": { "type": "string" }, "type": "array" }, "function": { "type": "string" }, "parameters": { "additionalProperties": { "additionalProperties": false, "properties": { "errors": { "items": { "type": "string" }, "type": "array" }, "result": { "enum": [ "valid", "invalid" ] }, "value": { "description": "The serialised value the server interpreted, or null if the parameter was not supplied." } }, "required": [ "result", "value" ], "type": "object" }, "description": "Per-parameter diagnostics keyed by api_name.", "type": "object" }, "result": { "enum": [ "valid", "invalid" ] } }, "required": [ "function", "result", "parameters" ], "type": "object" } } }, "description": "Validation outcome. `result` is `valid` or `invalid`; per-parameter diagnostics are always populated for every declared parameter." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Validate Suggest incidental hold (dry-run)", "tags": [ "booking" ] } }, "/v1/handset/session": { "post": { "description": "A shared floor handset (a `device` of kind `handset`) holds a client credential whose only scope is `handset:session`. With that bearer, the attendant presents their employee_id and PIN; the kernel verifies the PIN against the Argon2id hash on the `staff_member`, refuses any role that is not a floor role (housekeeper / housekeeping_supervisor / engineer / runner), and mints a user token whose principal IS that staff_member, carrying the role's per-action scope vector (no catch-all `actions:apply`, no guest PII), bound to the staff member's house (`property_id`). Lifetime is `AERANDIL_STAFF_SESSION_TTL` (a shift). Every rejection reads the same and takes the same time — unknown employee, no PIN set, wrong PIN, wrong role, a member of staff at no one house. Rate-limited per IP like `/oauth/token`.", "operationId": "aerandil_handset_session", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandsetSessionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandsetSessionResponse" } } }, "description": "Session opened; the token runs as the staff member.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The credentials were rejected (no detail by design)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The bearer does not hold `handset:session`." }, "429": { "description": "Per-IP rate limit exceeded (the `/oauth/token` limiter)." } }, "summary": "Open a shared-handset session for a staff member", "tags": [ "oauth" ] } }, "/v1/healthz": { "get": { "description": "Returns 200 when the process is up. No dependency checks — readiness lives at `/v1/readyz`.", "operationId": "aerandil_healthz", "responses": { "200": { "description": "Service is up." } }, "security": [], "summary": "Liveness probe", "tags": [ "system" ] } }, "/v1/housekeeping/pacing": { "get": { "description": "The housekeeping pacing report for one property and one business date — hubOS's productivity report, counted in OPERA's housekeeping credits. Per attendant: the credit target on their shift that day and the share of it completed (`target_percent`); credits assigned, completed, in progress and pending (pending or blocked) with their share of the assigned; rooms assigned, cleaned and on do-not-disturb; `cleaning_seconds` (`completed_at − started_at` of each complete task), `transition_seconds` (the gaps between one task's completion and the attendant's next start) and `deviation_seconds` (cleaning time less standard minutes, over the tasks that carry a standard — `standard_seconds`). The summary adds credits on tasks nobody holds (`credits_unassigned`), a count of unpriced tasks, and rooms on the board / assigned / cleaned / pending / inspected / on do-not-disturb. Skipped tasks count nowhere. \n\nCredits and standard minutes are what each task was minted with from the property's housekeeping credit rules (`set_housekeeping_credit_rule`); targets are set at `clock_in` or with `set_shift_credit_target`. A reader not cleared for staff data sees no targets. Computed on read from the tasks and shifts — the same value `hospitality.function.housekeeping_pacing` returns. \n\nLive data: always `Cache-Control: no-store`.", "operationId": "housekeeping_pacing", "parameters": [ { "description": "The property whose floor to read.", "in": "query", "name": "property_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "The business date, `YYYY-MM-DD`; omitted, the property's local calendar day — the day its housekeeping sheet is dated by.", "in": "query", "name": "business_date", "required": false, "schema": { "format": "date", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "attendants": { "items": { "properties": { "cleaning_seconds": { "type": "integer" }, "completed_percent": { "format": "decimal", "type": "string" }, "contracted_weekly_hours": { "format": "decimal", "type": "string" }, "credit_target": { "format": "decimal", "type": "string" }, "credits_assigned": { "format": "decimal", "type": "string" }, "credits_completed": { "format": "decimal", "type": "string" }, "credits_in_progress": { "format": "decimal", "type": "string" }, "credits_pending": { "format": "decimal", "type": "string" }, "deviation_seconds": { "type": "integer" }, "in_progress_percent": { "format": "decimal", "type": "string" }, "inspection_rating_average": { "format": "decimal", "type": "string" }, "inspections": { "type": "integer" }, "pending_percent": { "format": "decimal", "type": "string" }, "percentage_worked": { "format": "decimal", "type": "string" }, "rooms_assigned": { "type": "integer" }, "rooms_cleaned": { "type": "integer" }, "rooms_dnd": { "type": "integer" }, "self_rating_average": { "format": "decimal", "type": "string" }, "self_ratings": { "type": "integer" }, "staff_member_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "standard_seconds": { "type": "integer" }, "target_percent": { "format": "decimal", "type": "string" }, "time_worked_seconds": { "type": "integer" }, "transition_seconds": { "type": "integer" } }, "required": [ "staff_member_id", "credits_assigned", "credits_completed", "credits_in_progress", "credits_pending", "rooms_assigned", "rooms_cleaned", "rooms_dnd", "cleaning_seconds", "transition_seconds", "standard_seconds", "deviation_seconds", "inspections", "self_ratings" ], "type": "object" }, "type": "array" }, "business_date": { "format": "date", "type": "string" }, "property_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.property" }, "summary": { "properties": { "cleaning_seconds": { "type": "integer" }, "completed_percent": { "format": "decimal", "type": "string" }, "credits_assigned": { "format": "decimal", "type": "string" }, "credits_completed": { "format": "decimal", "type": "string" }, "credits_in_progress": { "format": "decimal", "type": "string" }, "credits_pending": { "format": "decimal", "type": "string" }, "credits_unassigned": { "format": "decimal", "type": "string" }, "deviation_seconds": { "type": "integer" }, "in_progress_percent": { "format": "decimal", "type": "string" }, "pending_percent": { "format": "decimal", "type": "string" }, "rooms": { "type": "integer" }, "rooms_assigned": { "type": "integer" }, "rooms_cleaned": { "type": "integer" }, "rooms_dnd": { "type": "integer" }, "rooms_inspected": { "type": "integer" }, "rooms_pending": { "type": "integer" }, "standard_seconds": { "type": "integer" }, "tasks_unpriced": { "type": "integer" }, "transition_seconds": { "type": "integer" } }, "required": [ "credits_assigned", "credits_completed", "credits_in_progress", "credits_pending", "credits_unassigned", "tasks_unpriced", "rooms", "rooms_assigned", "rooms_cleaned", "rooms_pending", "rooms_inspected", "rooms_dnd", "cleaning_seconds", "transition_seconds", "standard_seconds", "deviation_seconds" ], "type": "object" } }, "required": [ "property_id", "business_date", "summary", "attendants" ], "type": "object" } } }, "description": "The report. A day with no tasks is an empty report, not a 404.", "headers": { "Cache-Control": { "description": "Always `no-store` — live data.", "schema": { "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Token does not hold the function's grant — `functions:hospitality.function.housekeeping_pacing:invoke` (a housekeeping supervisor's handset carries it; an attendant's and a runner's do not) or the catch-all `functions:invoke` — or the session (a desk's or a handset's) is bound to another property." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No such property." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Malformed `business_date`." } }, "summary": "Read the housekeeping pacing report", "tags": [ "operations" ] } }, "/v1/interface-types": { "get": { "description": "Schema-discovery surface for the registry's interfaces — the structural contracts object types implement, each with the properties every implementer must expose and the implementers themselves. An implementer whose local property is named differently carries an explicit interface→local mapping; identity mappings are omitted rather than repeated. Sorted by `api_name` ascending. Returns `next_page_token: null` in v1 — ontology size stays under the pagination threshold.", "operationId": "list_interface_types", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "$ref": "#/components/schemas/InterfaceTypeSummary" }, "type": "array" }, "next_page_token": { "description": "Opaque cursor for the next page (AIP-158). Reserved for future growth; v1 returns `null` because the registry size is bounded.", "nullable": true, "type": "string" } }, "required": [ "data" ], "type": "object" } } }, "description": "Sorted summary list of every registered interface type." }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "List interface types", "tags": [ "metadata" ] } }, "/v1/invoices/{invoice_id}/dispatch": { "post": { "description": "Sends the document as a PDF attachment, then records the dispatch. That order is the contract: `record_invoice_dispatch` is the fact that a document *reached* someone, so a send that failed records nothing. The SMTP round trip happens outside any action transaction. `to` defaults to the address on the document's own recipient snapshot — a company's invoicing email when the recipient is a company, which is the accounts-payable address rather than whoever made the booking. A document may be sent more than once and does not change state by being sent. Gated on `issue_invoice`'s apply scope — whoever may issue the document may send it; `record_invoice_dispatch` itself is internal to the route, so a caller cannot assert a delivery that never happened.", "operationId": "dispatch_invoice", "parameters": [ { "description": "The issued document.", "in": "path", "name": "invoice_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DispatchInvoiceRequest" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DispatchInvoiceResponse" } } }, "description": "Accepted by the relay.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`recipient_email_missing` — the document carries no address and none was supplied; `invalid_recipient_email` — the address does not parse." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No outbound mail is configured on this deployment." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`mail_send_failed` — the relay refused or timed out." } }, "summary": "Email an issued document", "tags": [ "finance" ] } }, "/v1/invoices/{invoice_id}/pdf": { "get": { "description": "Serves the stored rendering when there is one and re-renders from the invoice's own snapshot when there is not — object storage disabled, an upload that failed, a tenant relocated without its bucket. The two are the same bytes: the renderer is deterministic with `issued_at` as its fixed timestamp. Requires clearance for the `pii.guest` marking on the recipient snapshot. Downloading a guest's invoice is reading a guest's name and address, so a caller without it gets `403` rather than a document with a blank addressee.", "operationId": "invoice_pdf", "parameters": [ { "description": "The issued document.", "in": "path", "name": "invoice_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/pdf": { "schema": { "format": "binary", "type": "string" } } }, "description": "The document, as a PDF.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Download an issued document", "tags": [ "finance" ] } }, "/v1/key-charge/tap": { "post": { "description": "The name-echo half of tap-to-charge: triggers an NFC read on a registered Adyen terminal and resolves the tapped card to its in-house stay, so staff can confirm the guest out loud before anything is posted. This route is the `resolve_access_credential` function invocation with a hardware pre-step, and carries that function's scope; the posting that follows the confirmation goes through the ordinary `post_charge_by_credential` action route, not this one. Resolution fails closed with a single generic error for unknown, revoked, expired and checked-out credentials alike — a probing caller learns nothing from which one it was. `501` unless `AERANDIL_ADYEN_ENABLED=1`.", "operationId": "key_charge_tap", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyChargeTapRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "credential": { "properties": { "credential_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.access_credential" }, "daily_cap": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "expires_at": { "format": "date-time", "type": "string" }, "folio_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.folio" }, "guest_name": { "type": "string" }, "kind": { "enum": [ "key_card", "wristband", "mobile_key", "other" ], "type": "string" }, "per_charge_cap": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "room_number": { "type": "string" }, "stay_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.stay" }, "token_hint": { "type": "string" } }, "required": [ "credential_id", "kind", "stay_id", "folio_id" ], "type": "object" }, "nfc_variant": { "description": "The terminal's reading of which card technology answered, when it reports one.", "type": [ "string", "null" ] }, "token": { "description": "The opaque vendor token read at tap time. Not the card's UID in the clear.", "type": "string" } }, "required": [ "token", "credential" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The card was read and resolved to a stay.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`terminal_busy` — the terminal is taking something else (a payment) or is not logged in; nothing was read and the terminal was left alone." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The device is not a payment terminal, not `active`, or carries no Adyen `POIID`, the read failed, or the tap resolved to nothing usable. One generic refusal by design." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The Adyen bridge is not enabled on this deployment." } }, "summary": "Trigger a key-card read on a registered terminal", "tags": [ "access" ] } }, "/v1/key-enrollment/read": { "post": { "description": "The desk's enrollment tap on a terminal (terminal-integration spec §4): triggers one NFC UID read on a registered Adyen terminal at the caller's house and answers the card's canonical token — uppercase hex, 8, 14 or 20 characters. It never resolves the token and never binds it: the desk binds it by applying `issue_access_credential` to the stay, which refuses a key still live on another stay. Carries `issue_access_credential`'s apply scope, since the read exists to feed it. Writes nothing, so it takes no `Idempotency-Key`; a repeat is another read. The request is held while someone taps, up to `AERANDIL_ADYEN_READ_TIMEOUT_SECS`. `501` unless `AERANDIL_ADYEN_ENABLED=1`.", "operationId": "key_enrollment_read", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyEnrollmentReadRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "nfc_variant": { "description": "The terminal's reading of which card technology answered, when it reports one.", "type": [ "string", "null" ] }, "token": { "description": "The card's canonical token — what `issue_access_credential` takes.", "type": "string" } }, "required": [ "token" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "A room key was read.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`terminal_busy` — the terminal is taking something else (a payment) or is not logged in; nothing was read and the terminal was left alone." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`device_not_terminal`, `device_not_active`, `device_missing_vendor_ref`; `not_a_key_card` — a payment card was tapped; `tap_timed_out` — nothing was tapped within the read budget, and the read was cancelled on the terminal; `terminal_read_failed` — the read did not succeed (cancelled on the terminal, a card error); `terminal_rejected` — Adyen never delivered the message (e.g. an unknown POIID); `token_malformed` — the UID breaks the token contract." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The Adyen bridge is not enabled on this deployment." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`terminal_unreachable` — the read never reached Adyen; `terminal_gateway_error` — Adyen answered with no reading." } }, "summary": "Read a room key's UID on a registered terminal, for enrollment", "tags": [ "access" ] } }, "/v1/link-types": { "get": { "description": "Schema-discovery surface for typed edges. Each entry names both directions (`from_role` / `to_role`) and the cardinality (`one_to_one` / `one_to_many` / `many_to_one` / `many_to_many`).", "operationId": "list_link_types", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "$ref": "#/components/schemas/LinkTypeSummary" }, "type": "array" }, "next_page_token": { "description": "Opaque cursor for the next page (AIP-158). Reserved for future growth; v1 returns `null` because the registry size is bounded.", "nullable": true, "type": "string" } }, "required": [ "data" ], "type": "object" } } }, "description": "Sorted summary list of every registered link type." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "List link types", "tags": [ "metadata" ] } }, "/v1/merchant-accounts/{merchant_account_id}/balance": { "get": { "description": "The hotel's money at Stripe now, read live as the hotel (`GET /v1/balance` with `Stripe-Account`): `available` and `pending` per currency (`connect_reserved` is the platform's field, never the hotel's). `next_payout` is the payout Stripe has already made when there is one (`basis: payout` — its arrival date and amount), else the earliest day the hotel's pending balance transactions become available and how much does that day (`basis: pending_balance`); the bank adds its own day or two. `in_flight` lists the payouts still on their way. The general manager's read (`analytics:read`), or the operator's; a desk session bound to another house is refused.", "operationId": "merchant_account_balance", "parameters": [ { "description": "The property's merchant account.", "in": "path", "name": "merchant_account_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "available": { "items": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "type": "array" }, "in_flight": { "items": { "type": "object" }, "type": "array" }, "merchant_account_id": { "format": "uuid", "type": "string" }, "next_payout": { "properties": { "amount": { "format": "decimal", "type": [ "string", "null" ] }, "available_on": { "description": "Forecast only: the earliest day that money becomes available (Stripe's `available_on`).", "format": "date", "type": [ "string", "null" ] }, "basis": { "enum": [ "payout", "pending_balance" ], "type": "string" }, "currency": { "type": [ "string", "null" ] }, "date": { "description": "The day the money is paid out: a payout's arrival day, or — forecast — the account's own payout day for its pending money (the anchor day of a weekly or monthly schedule); null for a manual account, which Stripe pays out only when asked.", "format": "date", "type": [ "string", "null" ] }, "interval": { "description": "Forecast only: the account's payout interval as Stripe reports it (`daily`, `weekly`, `monthly`, `manual`), null when not yet read.", "type": [ "string", "null" ] }, "payout_reference": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "observed_at": { "format": "date-time", "type": "string" }, "pending": { "items": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "type": "array" }, "property_id": { "format": "uuid", "type": "string" } }, "required": [ "merchant_account_id", "available", "pending", "next_payout", "in_flight" ], "type": "object" } } }, "description": "The balance and the next payout.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No card rail is configured on this deployment." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`rail_unavailable` — the card processor could not be reached (a transport failure, a 5xx, a 429, or this request's key still running at the processor). The balance was not read. Try again after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait before trying the same request again (RFC 9110 §10.2.3) — the queue's first backoff.", "schema": { "minimum": 0, "type": "integer" } } } } }, "security": [ { "aerandil_oauth": [ "analytics:read" ] }, { "aerandil_oauth": [ "tenant_admin:write" ] } ], "summary": "Read a merchant account's balance and next payout", "tags": [ "finance" ] } }, "/v1/merchant-accounts/{merchant_account_id}/card-export": { "get": { "description": "The Leaving policy's card export. The account's stored cards are Stripe PaymentMethods on Customers kept on the platform's account, so the platform files the move with Stripe: a partial copy to another Stripe account, or Stripe's PCI export to a processor that is not Stripe (runbook `products/payments/docs/leaving.md`). `shape=stripe_copy` (the default) is exactly the file Stripe's partial copy with CSV upload takes — \"a single-column of Stripe customer IDs (standard format: cus_xxxx) in a CSV file without a header\", one Customer per line, ordered. `shape=manifest` is a row per card under a header (`customer_id`, `payment_method_id`, `payment_card_id`, `person_id`, `reservation_id`, `brand`, `last4`, `expiry_month`, `expiry_year`), ordered by Customer then PaymentMethod: the join against Stripe's mapping file (`customer_id_old`, `source_id_old`, `customer_id_new`, `source_id_new`) and the list a PCI export request names. A card is a candidate when it names this account (`merchant_account_ref`), is `active`, is not past its expiry month on the house's business date, is the guest's own (`physical`), and has both of Stripe's handles. Whose each Customer is is proven at Stripe, not read off the card row: before either file is written every candidate Customer is read back and kept only when it exists, is not deleted, carries the rail's stamp naming this tenant and this account (`metadata[aerandil_tenant]`, `metadata[aerandil_merchant_account]`) and holds no PaymentMethod this account has no card for; a Customer with no stamp is withheld, never assumed. Stripe copies a Customer whole, so `Aerandil-Retired-Cards-Attached` counts the cards Stripe still has on an exported Customer that the file does not list (detach them before filing), and a Customer that also holds another merchant's or a channel's card, or that Stripe does not prove this account's, is left out and counted in `Aerandil-Customers-Withheld`. Every pull is recorded before the file is served — `cards_exported_at` and `cards_exported_count` on the account, and `merchant_account.cards.exported` with the counts and who asked. A closed account still exports. The platform operator's (`tenant_admin:write`), with clearance to read `payment.token` (`markings:payment.token:read`): Stripe's handles on a card are marked, and a bearer without the clearance is refused rather than handed a file of blanks.", "operationId": "merchant_account_card_export", "parameters": [ { "description": "The property's merchant account.", "in": "path", "name": "merchant_account_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "`stripe_copy` (default): Stripe's partial-copy upload. `manifest`: a row per card.", "in": "query", "name": "shape", "required": false, "schema": { "default": "stripe_copy", "enum": [ "stripe_copy", "manifest" ], "type": "string" } } ], "responses": { "200": { "content": { "text/csv": { "example": "cus_P1uBZ8nE2a7qXk\ncus_P1uC4Rk0xTq3Lm\n", "schema": { "type": "string" } } }, "description": "The export, as CSV.", "headers": { "Aerandil-Customers-Withheld": { "description": "Customers left out: they also hold a card another merchant, or a channel, may draw on, or Stripe does not prove them this account's.", "schema": { "minimum": 0, "type": "integer" } }, "Aerandil-Export-Cards": { "description": "How many cards the export carries.", "schema": { "minimum": 0, "type": "integer" } }, "Aerandil-Retired-Cards-Attached": { "description": "Cards Stripe still has on an exported Customer that the file does not list, which a copy of the Customer carries too.", "schema": { "minimum": 0, "type": "integer" } }, "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" }, "Content-Disposition": { "description": "`attachment`, named for the account and the shape.", "schema": { "type": "string" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`shape` is not `stripe_copy` or `manifest`." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The card rail is not configured on this deployment, so no Customer can be proven at Stripe (`stripe_not_configured`)." } }, "security": [ { "aerandil_oauth": [ "tenant_admin:write", "markings:payment.token:read" ] } ], "summary": "Export a merchant account's stored cards for the hotel's next processor", "tags": [ "finance" ] } }, "/v1/merchant-accounts/{merchant_account_id}/closure": { "post": { "description": "Stops settling the property's card payments to the account (`close_merchant_account`); the property then opens another or charges on the platform's own account again. Then rejects the account at Stripe (`reason=other`), which Stripe admits only once its balance is zero: until the hotel's last payout has landed the answer is `409 merchant_account_not_rejected` with the account already closed here, and the operator closes it again later. Terminal, and idempotent. Operator only (`tenant_admin:write`).", "operationId": "close_merchant_account", "parameters": [ { "description": "The property's merchant account.", "in": "path", "name": "merchant_account_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "merchant_account_id": { "format": "uuid", "type": "string" }, "rejected_at_stripe": { "enum": [ true ], "type": "boolean" }, "status": { "enum": [ "closed" ], "type": "string" } }, "required": [ "merchant_account_id", "status", "rejected_at_stripe" ], "type": "object" } } }, "description": "The account, closed.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`merchant_account_not_rejected` — closed here, but Stripe refused to reject the account (most often: its balance has not yet paid out). Close it again later." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No card rail is configured on this deployment." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`rail_unavailable` — the card processor could not be reached (a transport failure, a 5xx, a 429, or this request's key still running at the processor). The closure is finished later. Try again after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait before trying the same request again (RFC 9110 §10.2.3) — the queue's first backoff.", "schema": { "minimum": 0, "type": "integer" } } } } }, "security": [ { "aerandil_oauth": [ "tenant_admin:write" ] } ], "summary": "Close a merchant account", "tags": [ "finance" ] } }, "/v1/merchant-accounts/{merchant_account_id}/dashboard-link": { "post": { "description": "A one-time login link to the hotel's Stripe Express dashboard — its payouts, its bank details, its own view of the money. Only once the hotel has finished onboarding. The platform operator's (`tenant_admin:write`), or a manager's for the house their shift stands in (`merchant_accounts:dashboard`, held by the front-office manager's role; another house's account answers `403 property_out_of_scope`) — so a GM fixes the bank account a failed payout names without asking the platform.", "operationId": "merchant_account_dashboard_link", "parameters": [ { "description": "The property's merchant account.", "in": "path", "name": "merchant_account_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "url": { "format": "uri", "type": "string" } }, "required": [ "url" ], "type": "object" } } }, "description": "The login link.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`merchant_account_onboarding_incomplete` — the hotel has not finished Stripe's form." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No card rail is configured on this deployment." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`rail_unavailable` — the card processor could not be reached (a transport failure, a 5xx, a 429, or this request's key still running at the processor). No link was minted. Try again after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait before trying the same request again (RFC 9110 §10.2.3) — the queue's first backoff.", "schema": { "minimum": 0, "type": "integer" } } } } }, "security": [ { "aerandil_oauth": [ "tenant_admin:write" ] }, { "aerandil_oauth": [ "merchant_accounts:dashboard" ] } ], "summary": "Log the hotel in to its Stripe dashboard", "tags": [ "finance" ] } }, "/v1/merchant-accounts/{merchant_account_id}/dispute-costs": { "get": { "description": "The account's dispute cases opened in a year, per currency: how many, how many the house fought, won and lost, what was disputed and what was lost, and the network's dispute fees by who carried them — the platform (`platform_dispute_cost`: the received fee the processor never returns, plus every fee not passed through) and the hotel (`dispute_fee_recovered`, less a late win's refund). Under the published dispute line — Stripe's £20 received and £20 countered, the second back on a win, and neither on a lost case the kernel built — this is the hotel's own evidence of it. The general manager's read (`analytics:read`, from a desk shift at the house — another house's account is a `403 property_out_of_scope`) or the operator's (`tenant_admin:write`).", "operationId": "merchant_account_dispute_costs", "parameters": [ { "description": "The property's merchant account.", "in": "path", "name": "merchant_account_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "The year the cases were opened in, `YYYY`.", "in": "query", "name": "year", "required": true, "schema": { "pattern": "^[0-9]{4}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "dispute_costs": { "items": { "properties": { "cases": { "description": "Cases opened in the year.", "type": "integer" }, "currency": { "description": "ISO 4217 code of the cases' disputed amounts.", "type": "string" }, "disputed": { "description": "The sum of the disputed amounts.", "format": "decimal", "type": "string" }, "fees_carried_by_hotel": { "description": "The dispute fees recovered from the hotel, less what a late win handed back.", "format": "decimal", "type": "string" }, "fees_carried_by_platform": { "description": "The network's dispute fees the platform carried: the received fee the processor never returns, and every fee not passed through to the hotel (a written-off fee, a waived one).", "format": "decimal", "type": "string" }, "fees_waived": { "description": "Cases lost under the dispute-fee waiver: certified when their evidence was submitted, so neither of the network's fees was passed to the hotel (`dispute_fee_recovery = waived`).", "type": "integer" }, "fees_written_off": { "description": "Cases whose fee the hotel's balance could not cover after the card rail's last retry, or a person settled as not there (`dispute_fee_recovery = written_off`): the platform carries it.", "type": "integer" }, "fought": { "description": "Cases whose evidence reached the processor.", "type": "integer" }, "lost": { "type": "integer" }, "lost_amount": { "description": "The disputed amounts of the cases lost.", "format": "decimal", "type": "string" }, "open": { "description": "Cases not yet decided.", "type": "integer" }, "won": { "description": "Cases won, or prevented before they were filed.", "type": "integer" } }, "required": [ "currency", "cases", "fought", "won", "lost", "open", "disputed", "lost_amount", "fees_carried_by_platform", "fees_carried_by_hotel", "fees_waived", "fees_written_off" ], "type": "object" }, "type": "array" }, "merchant_account_id": { "format": "uuid", "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "year": { "type": "integer" } }, "required": [ "merchant_account_id", "year", "dispute_costs" ], "type": "object" } } }, "description": "The year's dispute cases and costs on the account.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`year` is missing or not `YYYY`." } }, "security": [ { "aerandil_oauth": [ "analytics:read" ] }, { "aerandil_oauth": [ "tenant_admin:write" ] } ], "summary": "Read what disputes cost the hotel in a year, and who paid", "tags": [ "finance" ] } }, "/v1/merchant-accounts/{merchant_account_id}/fee": { "post": { "description": "The platform's fee by card class — Stripe's published rate for the class plus a markup — through `set_merchant_account_fee`. Either `markup_bps` (laid over the account's own Stripe columns, its fixed fees passed through) or the whole `fee_schedule`, row by row. Applies to money captured from now on, holds already placed included. Operator only (`tenant_admin:write`).", "operationId": "set_merchant_account_fee", "parameters": [ { "description": "The property's merchant account.", "in": "path", "name": "merchant_account_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "fee_conversion_bps": { "description": "Stripe's currency-conversion fee; defaults to the account's.", "maximum": 10000, "minimum": 0, "type": "integer" }, "fee_schedule": { "items": { "$ref": "#/components/schemas/FeeScheduleRow" }, "type": "array" }, "markup_bps": { "description": "Basis points over Stripe's rate for every class (40 = Stripe + 0.40%). Not with `fee_schedule`.", "type": "integer" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeeScheduleResponse" } } }, "description": "The schedule, set.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Neither or both of markup_bps and fee_schedule; a class priced twice or not at all; a rate outside 0–10000 basis points; a negative fixed fee or two currencies; or the account is closed." } }, "security": [ { "aerandil_oauth": [ "tenant_admin:write" ] } ], "summary": "Set the platform's fee schedule on a merchant account", "tags": [ "finance" ] } }, "/v1/merchant-accounts/{merchant_account_id}/onboarding-link": { "post": { "description": "A fresh, single-use link into Stripe's hosted onboarding, valid for minutes. Not stored: it opens the hotel's identity details, so it goes straight to the person who asked. Stripe sends the hotel to `return_url` when it leaves the form, which says nothing about whether it finished: the account's state arrives by webhook, or by the sync route. Stripe's `refresh_url` is the kernel's own (`refresh_url` in the answer): a public, signed, one-use link, good for seven days: opening it shows a page with one button (`GET /v1/onboarding-links/{token}`, which spends nothing, so a mail scanner does no harm), and the button mints a fresh Stripe link with these parameters and redirects to it (`POST` to the same address) — so a hotel whose link expired needs no sign-in, and it is the link to send the hotel. A new link from this route retires the refresh link the hotel held before. Operator only (`tenant_admin:write`).", "operationId": "merchant_account_onboarding_link", "parameters": [ { "description": "The property's merchant account.", "in": "path", "name": "merchant_account_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "return_url": { "format": "uri", "type": "string" } }, "required": [ "return_url" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "expires_at": { "description": "When Stripe's link stops working — minutes away.", "format": "date-time", "type": [ "string", "null" ] }, "refresh_expires_at": { "format": "date-time", "type": "string" }, "refresh_url": { "description": "The kernel's one-use link that mints a fresh Stripe link — the one to send the hotel.", "format": "uri", "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "url", "refresh_url", "refresh_expires_at" ], "type": "object" } } }, "description": "Stripe's link, and the hotel's own refresh link.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`merchant_account_closed` — the account is closed." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`return_url` is not an absolute http(s) URL." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No card rail is configured on this deployment, or no public address (`public_base_url_not_configured`, `AERANDIL_PUBLIC_BASE_URL`)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`rail_unavailable` — the card processor could not be reached (a transport failure, a 5xx, a 429, or this request's key still running at the processor). No link was minted. Try again after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait before trying the same request again (RFC 9110 §10.2.3) — the queue's first backoff.", "schema": { "minimum": 0, "type": "integer" } } } } }, "security": [ { "aerandil_oauth": [ "tenant_admin:write" ] } ], "summary": "Send the hotel to Stripe's onboarding form", "tags": [ "finance" ] } }, "/v1/merchant-accounts/{merchant_account_id}/platform-earnings": { "get": { "description": "A fold over the platform's own balance transactions for one hotel's merchant account in the house's calendar month (`platform_ledger_line`, read off Stripe with the platform's key by the platform-ledger worker): the guest's money captured, refunds, the application fees earned, Stripe's processing fees paid, what chargebacks cost after pass-through (`dispute_costs`), the net of every line (`net_platform_earning`, to the penny) and what the fee and dispute lines do not explain (`unexplained` — a refund not reversed from the hotel, a capture never transferred). `variance` is Stripe's actual fee less the class estimate over the payments carrying both; `variance_gaps` counts the payments missing one side. The platform operator's read (`tenant_admin:write`): the margin and the variance are the platform's, never the hotel's — the night-audit close shows the hotel only what it paid.", "operationId": "merchant_account_platform_earnings", "parameters": [ { "description": "The property's merchant account.", "in": "path", "name": "merchant_account_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "The house's calendar month, `YYYY-MM`.", "in": "query", "name": "month", "required": true, "schema": { "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "case_count": { "type": "integer" }, "from": { "format": "date", "type": "string" }, "line_count": { "type": "integer" }, "merchant_account_id": { "format": "uuid", "type": "string" }, "month": { "type": "string" }, "payment_count": { "type": "integer" }, "property_id": { "format": "uuid", "type": "string" }, "to": { "format": "date", "type": "string" }, "totals": { "items": { "properties": { "currency": { "type": "string" }, "dispute_costs": { "properties": { "amounts_recovered": { "format": "decimal", "type": "string" }, "amounts_withdrawn": { "format": "decimal", "type": "string" }, "carried": { "format": "decimal", "type": "string" }, "fees_charged": { "format": "decimal", "type": "string" }, "fees_recovered": { "format": "decimal", "type": "string" } }, "type": "object" }, "gross_captured": { "format": "decimal", "type": "string" }, "net_platform_earning": { "format": "decimal", "type": "string" }, "platform_fees_earned": { "format": "decimal", "type": "string" }, "processor_fees_paid": { "format": "decimal", "type": "string" }, "refunded": { "format": "decimal", "type": "string" }, "unexplained": { "format": "decimal", "type": "string" }, "variance": { "properties": { "estimates": { "format": "decimal", "type": "string" }, "payments_compared": { "type": "integer" }, "processor_fees": { "format": "decimal", "type": "string" }, "variance": { "format": "decimal", "type": "string" } }, "type": "object" } }, "type": "object" }, "type": "array" }, "unmatched_count": { "type": "integer" }, "variance_gaps": { "properties": { "missing_actual": { "type": "integer" }, "missing_estimate": { "type": "integer" }, "other_currency": { "type": "integer" } }, "type": "object" } }, "required": [ "merchant_account_id", "month", "from", "to", "line_count", "unmatched_count", "totals", "variance_gaps" ], "type": "object" } } }, "description": "The month's platform earnings on the account.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`month` is missing or not `YYYY-MM`." } }, "security": [ { "aerandil_oauth": [ "tenant_admin:write" ] } ], "summary": "Read what the platform made and spent on a merchant account in a month", "tags": [ "finance" ] } }, "/v1/merchant-accounts/{merchant_account_id}/processing-fees": { "get": { "description": "What the hotel paid the platform for card processing in the house's calendar month, per currency: the application fees Stripe took on the account's charges (under the pricing decision, Stripe's published rate for the card's class plus 0.40%), net of the fees a refund handed back, and how many card payments paid one — read off the platform's own balance transactions (`platform_ledger_line`), the same fold as the night-audit close's `platform.processing_fees`, so the month is the sum of its days. Never the processor's actual fee, the variance or the margin: those are the operator's (`/platform-earnings`). The general manager's read (`analytics:read`, from a desk shift at the house — another house's account is a `403 property_out_of_scope`) or the operator's (`tenant_admin:write`).", "operationId": "merchant_account_processing_fees", "parameters": [ { "description": "The property's merchant account.", "in": "path", "name": "merchant_account_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "The house's calendar month, `YYYY-MM`.", "in": "query", "name": "month", "required": true, "schema": { "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "from": { "format": "date", "type": "string" }, "merchant_account_id": { "format": "uuid", "type": "string" }, "month": { "type": "string" }, "processing_fees": { "items": { "properties": { "charges": { "description": "Card payments that paid an application fee.", "type": "integer" }, "currency": { "type": "string" }, "total": { "description": "The application fees paid, net of fees refunded.", "format": "decimal", "type": "string" } }, "required": [ "currency", "charges", "total" ], "type": "object" }, "type": "array" }, "property_id": { "format": "uuid", "type": "string" }, "to": { "format": "date", "type": "string" } }, "required": [ "merchant_account_id", "month", "from", "to", "processing_fees" ], "type": "object" } } }, "description": "The month's card processing fees on the account.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`month` is missing or not `YYYY-MM`." } }, "security": [ { "aerandil_oauth": [ "analytics:read" ] }, { "aerandil_oauth": [ "tenant_admin:write" ] } ], "summary": "Read what the hotel paid for card processing in a month", "tags": [ "finance" ] } }, "/v1/merchant-accounts/{merchant_account_id}/sync": { "post": { "description": "Asks Stripe for the account's current state and records it with `record_merchant_account_state` — the moment the hotel returns from the form, or after a missed webhook. The `account.updated` webhook does the same as it happens. Operator only (`tenant_admin:write`).", "operationId": "sync_merchant_account", "parameters": [ { "description": "The property's merchant account.", "in": "path", "name": "merchant_account_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "charges_enabled": { "type": "boolean" }, "details_submitted": { "type": "boolean" }, "merchant_account_id": { "format": "uuid", "type": "string" }, "payouts_enabled": { "type": "boolean" }, "requirements_due": { "items": { "type": "string" }, "type": "array" }, "status": { "enum": [ "onboarding", "active", "restricted", "closed" ], "type": "string" } }, "required": [ "merchant_account_id", "status", "charges_enabled", "payouts_enabled", "details_submitted", "requirements_due" ], "type": "object" } } }, "description": "The account as Stripe reports it, now recorded.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No card rail is configured on this deployment." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`rail_unavailable` — the card processor could not be reached (a transport failure, a 5xx, a 429, or this request's key still running at the processor). The account was not read. Try again after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait before trying the same request again (RFC 9110 §10.2.3) — the queue's first backoff.", "schema": { "minimum": 0, "type": "integer" } } } } }, "security": [ { "aerandil_oauth": [ "tenant_admin:write" ] } ], "summary": "Read the account's verification back from Stripe", "tags": [ "finance" ] } }, "/v1/metrics": { "get": { "description": "Every registered metric's presentation surface: name, description, USALI lineage, declared caveats (typed disclosed limits), the unit its scalar carries, measures, dimensions, valid filter keys, grain, version, the rollup table + projection it reads, and the input events it is folded from (the provenance edge). Registry introspection — the values come from the schema, not the database. Query a metric at `GET /v1/metrics/{name}`.", "operationId": "list_metrics", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "caveats": { "items": { "properties": { "kind": { "type": "string" }, "note": { "type": "string" } }, "required": [ "kind", "note" ], "type": "object" }, "type": "array" }, "description": { "type": "string" }, "dimensions": { "items": { "type": "object" }, "type": "array" }, "grain": { "type": "string" }, "input_events": { "items": { "type": "string" }, "type": "array" }, "measures": { "items": { "type": "object" }, "type": "array" }, "name": { "type": "string" }, "projection_name": { "type": "string" }, "rollup_table": { "type": "string" }, "signed": { "description": "Whether negative values are meaningful — a signed metric (forecast bias) is read against zero, so centre the scale there rather than baselining at zero.", "type": "boolean" }, "unit": { "description": "What the metric's scalar is, as a display contract. `percent` is stored as the fraction (0.62, not 62); `native_unit` means the unit follows a dimension value (metered consumption: kWh / m³ / kg by `kind`), so a cross-dimension read mixes units.", "enum": [ "money", "ratio", "percent", "count", "hours", "native_unit" ], "type": "string" }, "usali_reference": { "type": "string" }, "valid_filters": { "items": { "type": "string" }, "type": "array" }, "version": { "type": "integer" } }, "required": [ "name", "measures", "dimensions", "grain", "version" ], "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "The metric catalogue, name-sorted." } }, "security": [ { "aerandil_oauth": [ "analytics:read" ] } ], "summary": "List the conformed-metric catalogue", "tags": [ "analytics" ] } }, "/v1/metrics/{name}": { "get": { "description": "Read a registered conformed metric — a ratio, mean, or sum of summed measures (ADR, RevPAR, cancellation rate, forecast bias) — aggregated over its rollup table and sliced by query-time dimensions (analytics decision doc 03 §5b). \n\n**Per-metric URL.** The metric name is the path segment, not a `?name=` parameter. An unregistered or unparseable name is `404` (the metric URL does not exist), distinct from a `422` for a request the metric cannot satisfy. \n\n**Dimensions and filters.** `dimensions` is a comma-separated group-by over the categorical axes the metric declares; `filters[]=` adds equality predicates over the metric's `valid_filters` subset. An axis or filter the metric does not declare is `422`. \n\n**Tenant-scoped.** The compiled query carries an explicit tenant predicate (RLS is defence-in-depth, not the only guard); a metric never reads across tenant boundaries. \n\n**Reads the rollup, never a live join.** The answer comes from the projection-maintained rollup; the query never falls through to a join over `objects` / `links`. A rollup that is not fresh enough is a structured `503`, never a slow correct answer. \n\n**Freshness gate (§5b.3, three tiers).** The owning projection's consumer lag and worker liveness combine with the rolled-up rows' wall-clock age: \n- **fresh** → `200`, `meta.stale = false`; \n- **soft-stale** (lag past `soft_lag_seq` *or* rows older than the metric's soft-staleness window) → `200` with `meta.stale = true` — the caller may serve the number with a freshness caveat; \n- **hard-stale** (lag at/over `hard_lag_seq`, rows past the hard-staleness window, or the projection's latest tick errored / it has never ticked) → `503` + `Retry-After`. The `503` body's `parameters` carry `required_rollup`, `checkpoint_lag_seq`, `row_freshness_seconds`, and `worker_unhealthy` for operator triage. \n\n`Retry-After` here means \"retry this same request once the projection catches up\" — distinct from a `412` \"re-read with a fresh ETag\". Live data: always `Cache-Control: no-store`.", "operationId": "metric_query", "parameters": [ { "description": "Registered metric name, e.g. `cancellation_rate`. Unknown names are `404`.", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } }, { "description": "Comma-separated categorical group-by axes the metric declares, e.g. `dimensions=property,channel`. Omitted → a single rolled-up row. An undeclared axis is `422`.", "example": "channel", "in": "query", "name": "dimensions", "required": false, "schema": { "type": "string" } }, { "description": "Per-dimension equality filters, rendered `filters[]=` (e.g. `filters[channel]=ota`). Only the metric's `valid_filters` dimensions are accepted; any other key is `422`.", "explode": true, "in": "query", "name": "filters", "required": false, "schema": { "additionalProperties": { "type": "string" }, "type": "object" }, "style": "deepObject" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricReadResponse" } } }, "description": "The aggregated metric. Covers both the fresh tier and the soft-stale tier — read `meta.stale` to tell them apart; `meta` also carries the lag and staleness inputs behind the decision.", "headers": { "Cache-Control": { "description": "Always `no-store` — live data.", "schema": { "const": "no-store", "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Token lacks the `analytics:read` scope." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No metric registered under that name." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation error — a requested dimension or filter the metric does not declare, or a malformed filter key." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The metric's rollup is hard-stale — the owning projection has lagged past `hard_lag_seq`, the rows are older than the hard-staleness window, or the projection is unhealthy. Retry after the projection catches up.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying the same request (RFC 9110 §10.2.3).", "schema": { "minimum": 0, "type": "integer" } } } } }, "security": [ { "aerandil_oauth": [ "analytics:read" ] } ], "summary": "Read a conformed metric", "tags": [ "analytics" ] } }, "/v1/object-types": { "get": { "description": "Schema-discovery surface — return every registered [`ObjectTypeDef`] in compact summary form. Companion to the OpenAPI document at `/v1/openapi.json`: both expose the registry, but this endpoint is friendlier to runtime introspection (no schema-walk needed) and ships the `display_name`/`description`/`markings` operator fields that the per-type JSON Schemas don't surface. Sorted by `api_name` ascending. Returns `next_page_token: null` in v1 — ontology size stays under the pagination threshold.", "operationId": "list_object_types", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "$ref": "#/components/schemas/ObjectTypeSummary" }, "type": "array" }, "next_page_token": { "description": "Opaque cursor for the next page (AIP-158). Reserved for future growth; v1 returns `null` because the registry size is bounded.", "nullable": true, "type": "string" } }, "required": [ "data" ], "type": "object" } } }, "description": "Sorted summary list of every registered object type." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "List object types", "tags": [ "metadata" ] } }, "/v1/object-types/hospitality.access_credential/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA per-stay physical or virtual credential — the room key card, wristband, or mobile key — bound to a stay so the opaque vendor token a reader picks up at tap time resolves to the stay's open folio. The token is a locator, never an authenticator (card UIDs are clonable): resolution requires `status = active`, an unexpired `expires_at`, and an in-house stay, and every posting is bounded by the credential's `per_charge_cap` / `daily_cap`. Check-out revokes every credential on the stay — a dropped card in the express-checkout box must fail closed.", "operationId": "get_hospitality_access_credential", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.access_credential" }, "properties": { "additionalProperties": false, "properties": { "daily_cap": { "description": "Maximum total the credential may post per property-local business day", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Access credential daily cap", "type": "object" }, "expires_at": { "format": "date-time", "title": "Hard expiry — resolution fails closed past this instant", "type": "string" }, "id": { "title": "Credential id", "type": "string" }, "issued_at": { "format": "date-time", "title": "When the credential was issued", "type": "string" }, "kind": { "enum": [ "key_card", "wristband", "mobile_key", "other" ], "title": "Credential form", "type": "string" }, "per_charge_cap": { "description": "Maximum amount a single tap may post", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Access credential per charge cap", "type": "object" }, "revoked_at": { "format": "date-time", "title": "When the credential was revoked", "type": "string" }, "status": { "enum": [ "active", "revoked" ], "title": "Lifecycle status", "type": "string" }, "token": { "title": "Opaque vendor token (card UID — present only while active)", "type": "string" }, "token_hint": { "title": "Display fragment of the token (last four) for staff UIs and audit", "type": "string" } }, "required": [ "id", "kind", "status", "issued_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.access_credential:read" ] } ], "summary": "Read Access credential", "tags": [ "access" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.access_credential/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA per-stay physical or virtual credential — the room key card, wristband, or mobile key — bound to a stay so the opaque vendor token a reader picks up at tap time resolves to the stay's open folio. The token is a locator, never an authenticator (card UIDs are clonable): resolution requires `status = active`, an unexpired `expires_at`, and an in-house stay, and every posting is bounded by the credential's `per_charge_cap` / `daily_cap`. Check-out revokes every credential on the stay — a dropped card in the express-checkout box must fail closed.", "operationId": "get_hospitality_access_credential_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.access_credential" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.access_credential:read" ] } ], "summary": "Read Access credential as of a watermark", "tags": [ "access" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.access_credential/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA per-stay physical or virtual credential — the room key card, wristband, or mobile key — bound to a stay so the opaque vendor token a reader picks up at tap time resolves to the stay's open folio. The token is a locator, never an authenticator (card UIDs are clonable): resolution requires `status = active`, an unexpired `expires_at`, and an in-house stay, and every posting is bounded by the credential's `per_charge_cap` / `daily_cap`. Check-out revokes every credential on the stay — a dropped card in the express-checkout box must fail closed.", "operationId": "list_links_hospitality_access_credential", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.access_credential:read" ] } ], "summary": "List links of Access credential", "tags": [ "access" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.access_credential_for_stay", "hospitality.link.charge_via_credential" ] } } ] }, "/v1/object-types/hospitality.access_credential/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA per-stay physical or virtual credential — the room key card, wristband, or mobile key — bound to a stay so the opaque vendor token a reader picks up at tap time resolves to the stay's open folio. The token is a locator, never an authenticator (card UIDs are clonable): resolution requires `status = active`, an unexpired `expires_at`, and an in-house stay, and every posting is bounded by the credential's `per_charge_cap` / `daily_cap`. Check-out revokes every credential on the stay — a dropped card in the express-checkout box must fail closed.", "operationId": "traverse_hospitality_access_credential", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.access_credential_for_stay", "hospitality.link.charge_via_credential" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.access_credential:read" ] } ], "summary": "Traverse from Access credential", "tags": [ "access" ] } }, "/v1/object-types/hospitality.access_credential/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA per-stay physical or virtual credential — the room key card, wristband, or mobile key — bound to a stay so the opaque vendor token a reader picks up at tap time resolves to the stay's open folio. The token is a locator, never an authenticator (card UIDs are clonable): resolution requires `status = active`, an unexpired `expires_at`, and an in-house stay, and every posting is bounded by the credential's `per_charge_cap` / `daily_cap`. Check-out revokes every credential on the stay — a dropped card in the express-checkout box must fail closed.", "operationId": "search_hospitality_access_credential", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "key_card", "wristband", "mobile_key", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "revoked" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "token" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "token" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "token" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "token" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "token_hint" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "token_hint" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "token_hint" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "token_hint" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revoked_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revoked_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revoked_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "per_charge_cap" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "daily_cap" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "kind", "status", "token", "token_hint", "issued_at", "expires_at", "revoked_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.access_credential" }, "properties": { "additionalProperties": false, "properties": { "daily_cap": { "description": "Maximum total the credential may post per property-local business day", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Access credential daily cap", "type": "object" }, "expires_at": { "format": "date-time", "title": "Hard expiry — resolution fails closed past this instant", "type": "string" }, "id": { "title": "Credential id", "type": "string" }, "issued_at": { "format": "date-time", "title": "When the credential was issued", "type": "string" }, "kind": { "enum": [ "key_card", "wristband", "mobile_key", "other" ], "title": "Credential form", "type": "string" }, "per_charge_cap": { "description": "Maximum amount a single tap may post", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Access credential per charge cap", "type": "object" }, "revoked_at": { "format": "date-time", "title": "When the credential was revoked", "type": "string" }, "status": { "enum": [ "active", "revoked" ], "title": "Lifecycle status", "type": "string" }, "token": { "title": "Opaque vendor token (card UID — present only while active)", "type": "string" }, "token_hint": { "title": "Display fragment of the token (last four) for staff UIs and audit", "type": "string" } }, "required": [ "id", "kind", "status", "issued_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.access_credential:read" ] } ], "summary": "Search Access credential", "tags": [ "access" ] } }, "/v1/object-types/hospitality.access_purpose/objects/{id}": { "get": { "description": "Read an existing instance.\n\nAn operator-defined purpose for accessing marked data — the PBAC vocabulary entry (e.g. `chargeback investigation`). Names the marking compartments it can unlock (`covered_markings`) and bounds how long a grant of it may live. A purpose is a definition, not a permission: nothing is conferred until a `purpose_grant` is approved. While a tenant has an `active` purpose covering a marking and the deployment enforces PBAC, bearer clearances for that marking require an active grant.", "operationId": "get_hospitality_access_purpose", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.access_purpose" }, "properties": { "additionalProperties": false, "properties": { "covered_markings": { "title": "Marking api-names this purpose can unlock (JSON array, e.g. [\"pii.guest\"]); validated against the registered marking catalogue" }, "display_name": { "title": "Operator-facing name", "type": "string" }, "id": { "title": "Purpose id", "type": "string" }, "justification": { "title": "Why this purpose exists — the standing business/legal ground grants under it inherit (distinct from each grant's own rationale)", "type": "string" }, "max_grant_hours": { "title": "Ceiling on a grant's lifetime under this purpose; a `request_purpose_grant` asking for longer is rejected", "type": "integer" }, "status": { "enum": [ "active", "retired" ], "title": "Lifecycle status", "type": "string" } }, "required": [ "id", "display_name", "justification", "covered_markings", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.access_purpose:read" ] } ], "summary": "Read Access purpose", "tags": [ "pbac" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.access_purpose/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nAn operator-defined purpose for accessing marked data — the PBAC vocabulary entry (e.g. `chargeback investigation`). Names the marking compartments it can unlock (`covered_markings`) and bounds how long a grant of it may live. A purpose is a definition, not a permission: nothing is conferred until a `purpose_grant` is approved. While a tenant has an `active` purpose covering a marking and the deployment enforces PBAC, bearer clearances for that marking require an active grant.", "operationId": "get_hospitality_access_purpose_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.access_purpose" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.access_purpose:read" ] } ], "summary": "Read Access purpose as of a watermark", "tags": [ "pbac" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.access_purpose/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nAn operator-defined purpose for accessing marked data — the PBAC vocabulary entry (e.g. `chargeback investigation`). Names the marking compartments it can unlock (`covered_markings`) and bounds how long a grant of it may live. A purpose is a definition, not a permission: nothing is conferred until a `purpose_grant` is approved. While a tenant has an `active` purpose covering a marking and the deployment enforces PBAC, bearer clearances for that marking require an active grant.", "operationId": "list_links_hospitality_access_purpose", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.access_purpose:read" ] } ], "summary": "List links of Access purpose", "tags": [ "pbac" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.purpose_grant_for_purpose" ] } } ] }, "/v1/object-types/hospitality.access_purpose/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nAn operator-defined purpose for accessing marked data — the PBAC vocabulary entry (e.g. `chargeback investigation`). Names the marking compartments it can unlock (`covered_markings`) and bounds how long a grant of it may live. A purpose is a definition, not a permission: nothing is conferred until a `purpose_grant` is approved. While a tenant has an `active` purpose covering a marking and the deployment enforces PBAC, bearer clearances for that marking require an active grant.", "operationId": "traverse_hospitality_access_purpose", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.purpose_grant_for_purpose" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.access_purpose:read" ] } ], "summary": "Traverse from Access purpose", "tags": [ "pbac" ] } }, "/v1/object-types/hospitality.access_purpose/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nAn operator-defined purpose for accessing marked data — the PBAC vocabulary entry (e.g. `chargeback investigation`). Names the marking compartments it can unlock (`covered_markings`) and bounds how long a grant of it may live. A purpose is a definition, not a permission: nothing is conferred until a `purpose_grant` is approved. While a tenant has an `active` purpose covering a marking and the deployment enforces PBAC, bearer clearances for that marking require an active grant.", "operationId": "search_hospitality_access_purpose", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "justification" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "justification" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "covered_markings" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_grant_hours" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_grant_hours" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_grant_hours" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "retired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "display_name", "justification", "max_grant_hours", "status" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.access_purpose" }, "properties": { "additionalProperties": false, "properties": { "covered_markings": { "title": "Marking api-names this purpose can unlock (JSON array, e.g. [\"pii.guest\"]); validated against the registered marking catalogue" }, "display_name": { "title": "Operator-facing name", "type": "string" }, "id": { "title": "Purpose id", "type": "string" }, "justification": { "title": "Why this purpose exists — the standing business/legal ground grants under it inherit (distinct from each grant's own rationale)", "type": "string" }, "max_grant_hours": { "title": "Ceiling on a grant's lifetime under this purpose; a `request_purpose_grant` asking for longer is rejected", "type": "integer" }, "status": { "enum": [ "active", "retired" ], "title": "Lifecycle status", "type": "string" } }, "required": [ "id", "display_name", "justification", "covered_markings", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.access_purpose:read" ] } ], "summary": "Search Access purpose", "tags": [ "pbac" ] } }, "/v1/object-types/hospitality.agent_eval_case/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne agent-run eval case, promoted from a production session trace (`promote_agent_trace_to_eval_case`). Carries the task and a graders array in the runtime's agent-run suite grammar (`run.completes` / `run.proposes` / `run.never_calls` / `final.mentions`); the runtime merges `active` registry cases with file-based suites at eval time (`retire_agent_eval_case` is the off-ramp). `source_session_id` is the provenance pointer back to the trace the case was minted from.", "operationId": "get_hospitality_agent_eval_case", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_eval_case" }, "properties": { "additionalProperties": false, "properties": { "agent_key": { "title": "The agent definition this case evaluates", "type": "string" }, "case_name": { "title": "Suite-unique case name", "type": "string" }, "graders": { "title": "Graders array in the agent-run suite grammar (JSON)" }, "id": { "title": "Eval case id", "type": "string" }, "promoted_at": { "format": "date-time", "title": "When the case was promoted", "type": "string" }, "promoted_by": { "title": "`principal.stable_id()` of the promoter", "type": "string" }, "retired_at": { "format": "date-time", "title": "When the case was retired", "type": "string" }, "retired_by": { "title": "`principal.stable_id()` of the retirer", "type": "string" }, "retired_reason": { "title": "Why the case was retired", "type": "string" }, "source_session_id": { "title": "The session trace this case was promoted from", "type": "string" }, "status": { "enum": [ "active", "retired" ], "title": "Lifecycle: `active` joins the effective suite; `retired` is the off-ramp for a mistaken promotion or a stale subject (retire_agent_eval_case)", "type": "string" }, "task": { "title": "The task handed to the agent", "type": "string" } }, "required": [ "id", "agent_key", "case_name", "graders", "source_session_id", "promoted_at", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.agent_eval_case:read" ] } ], "summary": "Read Agent eval case", "tags": [ "agents" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.agent_eval_case/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne agent-run eval case, promoted from a production session trace (`promote_agent_trace_to_eval_case`). Carries the task and a graders array in the runtime's agent-run suite grammar (`run.completes` / `run.proposes` / `run.never_calls` / `final.mentions`); the runtime merges `active` registry cases with file-based suites at eval time (`retire_agent_eval_case` is the off-ramp). `source_session_id` is the provenance pointer back to the trace the case was minted from.", "operationId": "get_hospitality_agent_eval_case_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.agent_eval_case" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.agent_eval_case:read" ] } ], "summary": "Read Agent eval case as of a watermark", "tags": [ "agents" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.agent_eval_case/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne agent-run eval case, promoted from a production session trace (`promote_agent_trace_to_eval_case`). Carries the task and a graders array in the runtime's agent-run suite grammar (`run.completes` / `run.proposes` / `run.never_calls` / `final.mentions`); the runtime merges `active` registry cases with file-based suites at eval time (`retire_agent_eval_case` is the off-ramp). `source_session_id` is the provenance pointer back to the trace the case was minted from.", "operationId": "search_hospitality_agent_eval_case", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_key" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_key" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_key" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_key" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "case_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "case_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "case_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "case_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "task" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "task" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "graders" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source_session_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source_session_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source_session_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source_session_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "promoted_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "promoted_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "promoted_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "promoted_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "promoted_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "promoted_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "promoted_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "retired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "agent_key", "case_name", "task", "source_session_id", "promoted_by", "promoted_at", "status", "retired_at", "retired_by", "retired_reason" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_eval_case" }, "properties": { "additionalProperties": false, "properties": { "agent_key": { "title": "The agent definition this case evaluates", "type": "string" }, "case_name": { "title": "Suite-unique case name", "type": "string" }, "graders": { "title": "Graders array in the agent-run suite grammar (JSON)" }, "id": { "title": "Eval case id", "type": "string" }, "promoted_at": { "format": "date-time", "title": "When the case was promoted", "type": "string" }, "promoted_by": { "title": "`principal.stable_id()` of the promoter", "type": "string" }, "retired_at": { "format": "date-time", "title": "When the case was retired", "type": "string" }, "retired_by": { "title": "`principal.stable_id()` of the retirer", "type": "string" }, "retired_reason": { "title": "Why the case was retired", "type": "string" }, "source_session_id": { "title": "The session trace this case was promoted from", "type": "string" }, "status": { "enum": [ "active", "retired" ], "title": "Lifecycle: `active` joins the effective suite; `retired` is the off-ramp for a mistaken promotion or a stale subject (retire_agent_eval_case)", "type": "string" }, "task": { "title": "The task handed to the agent", "type": "string" } }, "required": [ "id", "agent_key", "case_name", "graders", "source_session_id", "promoted_at", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.agent_eval_case:read" ] } ], "summary": "Search Agent eval case", "tags": [ "agents" ] } }, "/v1/object-types/hospitality.agent_installation/objects/{id}": { "get": { "description": "Read an existing instance.\n\nTenant / property enablement of a registry entry. Permission-bearing — `enabled` installations are what `enable_agent_installation` issues per-tenant. `enabled_action_scopes` and `enabled_function_scopes` are subsets of the registry entry's declared maxima. `installed_scope_ref` is required and type-checked for non-tenant scopes; the broad catch-all scopes (`actions:apply`, `functions:invoke`) and any `internal:workflow:*` scope are rejected at install time.", "operationId": "get_hospitality_agent_installation", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_installation" }, "properties": { "additionalProperties": false, "properties": { "allowed_workflow_keys": { "items": { "type": "string" }, "title": "Optional workflow-key allowlist; empty/null means action/function scopes decide", "type": "array" }, "approval_policy": { "title": "Gates required before this agent can execute high-risk steps. Required when any enabled action / function / allowed workflow has a risk_tier in the high-risk set (per `agent_installation_high_risk_requires_policy`)." }, "auth_mode": { "enum": [ "none", "oauth_client_credentials", "oauth_delegated", "api_key_reference", "jwt_exchange", "mcp_oauth" ], "title": "How the installation authenticates the agent at call time", "type": "string" }, "credential_reference": { "title": "Opaque pointer into an external secret manager. `credential_reference_no_secret_material` rejects obvious secret bodies (bearer tokens, API keys, PEM blocks).", "type": "string" }, "dispatch_endpoint_url": { "title": "Runtime-published URL the proposal 0022 dispatcher POSTs signed task envelopes to (§6.1 rules: https required, http admissible only for loopback receivers). Unset = this installation is not dispatch-taskable.", "type": "string" }, "enabled_action_scopes": { "items": { "type": "string" }, "title": "Subset of the registry entry's declared action scopes", "type": "array" }, "enabled_at": { "format": "date-time", "title": "Enablement time", "type": "string" }, "enabled_by": { "title": "Principal stable id that approved enablement", "type": "string" }, "enabled_data_classes": { "items": { "enum": [ "public", "operational", "guest_pii", "staff_pii", "payment_metadata", "regulated_health", "secrets" ], "type": "string" }, "title": "Subset of the registry entry's declared data classes", "type": "array" }, "enabled_function_scopes": { "items": { "type": "string" }, "title": "Subset of the registry entry's declared function scopes", "type": "array" }, "enabled_read_scopes": { "items": { "type": "string" }, "title": "Subset of the registry entry's declared read scopes. When present it is the installation's whole object-read grant: a token minted for it carries `objects::read` for exactly these types and never the broad `objects:read`. Absent, reads are not narrowed by the installation.", "type": "array" }, "expires_at": { "format": "date-time", "title": "Optional time-bound install", "type": "string" }, "id": { "title": "Installation id", "type": "string" }, "installation_status": { "enum": [ "requested", "enabled", "suspended", "revoked", "disabled", "expired" ], "title": "Lifecycle status", "type": "string" }, "installed_by": { "title": "Principal stable id of the installer", "type": "string" }, "installed_scope": { "enum": [ "tenant", "brand", "portfolio", "property", "venue" ], "title": "Tenancy scope this installation grants access at", "type": "string" }, "installed_scope_ref": { "description": "Typed reference to the scoping object. Required for non-tenant scopes; forbidden for `installed_scope = tenant`. Type-checked by `agent_installation_scope_ref_coherent`.", "properties": { "object_id": { "type": "string" }, "object_type": { "type": "string" } }, "required": [ "object_type", "object_id" ], "title": "Agent installation installed scope ref", "type": "object" }, "last_used_at": { "format": "date-time", "title": "Updated by agent-run attribution", "type": "string" }, "runner_identity_ref": { "title": "Stable §8.3 identity URI the runtime presents in its signed acks/results (SPIFFE URI, JWK URL, or urn:aerandil form).", "type": "string" }, "runner_public_keys": { "title": "kid → base64 Ed25519 verification keys (RFC 8032 raw 32-byte) the receiver routes verify this installation's ack / result_submit envelope signatures against. Public key material only — rotation is additive (keep old + new kid during the window)." }, "suspended_at": { "format": "date-time", "title": "Suspension time", "type": "string" }, "suspension_reason": { "title": "Required when suspended / revoked", "type": "string" } }, "required": [ "id", "installation_status", "installed_scope", "enabled_action_scopes", "enabled_function_scopes", "enabled_data_classes", "auth_mode" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.agent_installation:read" ] } ], "summary": "Read Agent installation", "tags": [ "agents" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.agent_installation/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nTenant / property enablement of a registry entry. Permission-bearing — `enabled` installations are what `enable_agent_installation` issues per-tenant. `enabled_action_scopes` and `enabled_function_scopes` are subsets of the registry entry's declared maxima. `installed_scope_ref` is required and type-checked for non-tenant scopes; the broad catch-all scopes (`actions:apply`, `functions:invoke`) and any `internal:workflow:*` scope are rejected at install time.", "operationId": "get_hospitality_agent_installation_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.agent_installation" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.agent_installation:read" ] } ], "summary": "Read Agent installation as of a watermark", "tags": [ "agents" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.agent_installation/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nTenant / property enablement of a registry entry. Permission-bearing — `enabled` installations are what `enable_agent_installation` issues per-tenant. `enabled_action_scopes` and `enabled_function_scopes` are subsets of the registry entry's declared maxima. `installed_scope_ref` is required and type-checked for non-tenant scopes; the broad catch-all scopes (`actions:apply`, `functions:invoke`) and any `internal:workflow:*` scope are rejected at install time.", "operationId": "list_links_hospitality_agent_installation", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.agent_installation:read" ] } ], "summary": "List links of Agent installation", "tags": [ "agents" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.agent_installation_for_registry_entry", "hospitality.link.federated_local_runner_agent_installation", "hospitality.link.workflow_run_started_by_agent_installation", "hospitality.link.workflow_step_run_used_agent_installation" ] } } ] }, "/v1/object-types/hospitality.agent_installation/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nTenant / property enablement of a registry entry. Permission-bearing — `enabled` installations are what `enable_agent_installation` issues per-tenant. `enabled_action_scopes` and `enabled_function_scopes` are subsets of the registry entry's declared maxima. `installed_scope_ref` is required and type-checked for non-tenant scopes; the broad catch-all scopes (`actions:apply`, `functions:invoke`) and any `internal:workflow:*` scope are rejected at install time.", "operationId": "traverse_hospitality_agent_installation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.agent_installation_for_registry_entry", "hospitality.link.federated_local_runner_agent_installation", "hospitality.link.workflow_run_started_by_agent_installation", "hospitality.link.workflow_step_run_used_agent_installation" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.agent_installation:read" ] } ], "summary": "Traverse from Agent installation", "tags": [ "agents" ] } }, "/v1/object-types/hospitality.agent_installation/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nTenant / property enablement of a registry entry. Permission-bearing — `enabled` installations are what `enable_agent_installation` issues per-tenant. `enabled_action_scopes` and `enabled_function_scopes` are subsets of the registry entry's declared maxima. `installed_scope_ref` is required and type-checked for non-tenant scopes; the broad catch-all scopes (`actions:apply`, `functions:invoke`) and any `internal:workflow:*` scope are rejected at install time.", "operationId": "search_hospitality_agent_installation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "installation_status" }, "type": { "const": "eq" }, "value": { "enum": [ "requested", "enabled", "suspended", "revoked", "disabled", "expired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "installed_scope" }, "type": { "const": "eq" }, "value": { "enum": [ "tenant", "brand", "portfolio", "property", "venue" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "installed_scope_ref" }, "type": { "const": "eq" }, "value": { "properties": { "object_id": { "type": "string" }, "object_type": { "type": "string" } }, "required": [ "object_type", "object_id" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "enabled_action_scopes" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "enabled_function_scopes" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "enabled_read_scopes" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "enabled_data_classes" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "public", "operational", "guest_pii", "staff_pii", "payment_metadata", "regulated_health", "secrets" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "credential_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "credential_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "credential_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "credential_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "auth_mode" }, "type": { "const": "eq" }, "value": { "enum": [ "none", "oauth_client_credentials", "oauth_delegated", "api_key_reference", "jwt_exchange", "mcp_oauth" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "installed_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "installed_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "installed_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "installed_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "enabled_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "enabled_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "enabled_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "enabled_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "enabled_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "enabled_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "enabled_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "suspended_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "suspended_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "suspended_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "suspension_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "suspension_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_used_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_used_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_used_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approval_policy" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "allowed_workflow_keys" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispatch_endpoint_url" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispatch_endpoint_url" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispatch_endpoint_url" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispatch_endpoint_url" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "runner_identity_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "runner_identity_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "runner_identity_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "runner_identity_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "runner_public_keys" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "installation_status", "installed_scope", "credential_reference", "auth_mode", "installed_by", "enabled_by", "enabled_at", "suspended_at", "suspension_reason", "expires_at", "last_used_at", "dispatch_endpoint_url", "runner_identity_ref" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_installation" }, "properties": { "additionalProperties": false, "properties": { "allowed_workflow_keys": { "items": { "type": "string" }, "title": "Optional workflow-key allowlist; empty/null means action/function scopes decide", "type": "array" }, "approval_policy": { "title": "Gates required before this agent can execute high-risk steps. Required when any enabled action / function / allowed workflow has a risk_tier in the high-risk set (per `agent_installation_high_risk_requires_policy`)." }, "auth_mode": { "enum": [ "none", "oauth_client_credentials", "oauth_delegated", "api_key_reference", "jwt_exchange", "mcp_oauth" ], "title": "How the installation authenticates the agent at call time", "type": "string" }, "credential_reference": { "title": "Opaque pointer into an external secret manager. `credential_reference_no_secret_material` rejects obvious secret bodies (bearer tokens, API keys, PEM blocks).", "type": "string" }, "dispatch_endpoint_url": { "title": "Runtime-published URL the proposal 0022 dispatcher POSTs signed task envelopes to (§6.1 rules: https required, http admissible only for loopback receivers). Unset = this installation is not dispatch-taskable.", "type": "string" }, "enabled_action_scopes": { "items": { "type": "string" }, "title": "Subset of the registry entry's declared action scopes", "type": "array" }, "enabled_at": { "format": "date-time", "title": "Enablement time", "type": "string" }, "enabled_by": { "title": "Principal stable id that approved enablement", "type": "string" }, "enabled_data_classes": { "items": { "enum": [ "public", "operational", "guest_pii", "staff_pii", "payment_metadata", "regulated_health", "secrets" ], "type": "string" }, "title": "Subset of the registry entry's declared data classes", "type": "array" }, "enabled_function_scopes": { "items": { "type": "string" }, "title": "Subset of the registry entry's declared function scopes", "type": "array" }, "enabled_read_scopes": { "items": { "type": "string" }, "title": "Subset of the registry entry's declared read scopes. When present it is the installation's whole object-read grant: a token minted for it carries `objects::read` for exactly these types and never the broad `objects:read`. Absent, reads are not narrowed by the installation.", "type": "array" }, "expires_at": { "format": "date-time", "title": "Optional time-bound install", "type": "string" }, "id": { "title": "Installation id", "type": "string" }, "installation_status": { "enum": [ "requested", "enabled", "suspended", "revoked", "disabled", "expired" ], "title": "Lifecycle status", "type": "string" }, "installed_by": { "title": "Principal stable id of the installer", "type": "string" }, "installed_scope": { "enum": [ "tenant", "brand", "portfolio", "property", "venue" ], "title": "Tenancy scope this installation grants access at", "type": "string" }, "installed_scope_ref": { "description": "Typed reference to the scoping object. Required for non-tenant scopes; forbidden for `installed_scope = tenant`. Type-checked by `agent_installation_scope_ref_coherent`.", "properties": { "object_id": { "type": "string" }, "object_type": { "type": "string" } }, "required": [ "object_type", "object_id" ], "title": "Agent installation installed scope ref", "type": "object" }, "last_used_at": { "format": "date-time", "title": "Updated by agent-run attribution", "type": "string" }, "runner_identity_ref": { "title": "Stable §8.3 identity URI the runtime presents in its signed acks/results (SPIFFE URI, JWK URL, or urn:aerandil form).", "type": "string" }, "runner_public_keys": { "title": "kid → base64 Ed25519 verification keys (RFC 8032 raw 32-byte) the receiver routes verify this installation's ack / result_submit envelope signatures against. Public key material only — rotation is additive (keep old + new kid during the window)." }, "suspended_at": { "format": "date-time", "title": "Suspension time", "type": "string" }, "suspension_reason": { "title": "Required when suspended / revoked", "type": "string" } }, "required": [ "id", "installation_status", "installed_scope", "enabled_action_scopes", "enabled_function_scopes", "enabled_data_classes", "auth_mode" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.agent_installation:read" ] } ], "summary": "Search Agent installation", "tags": [ "agents" ] } }, "/v1/object-types/hospitality.agent_registry_entry/objects/{id}": { "get": { "description": "Read an existing instance.\n\nCatalog metadata for a first-party or third-party agent, MCP server, or agent skill. Declares maximum action / function / data-class scopes the agent claims to need plus vendor / model / safety metadata. **A registry entry is not permission to run** — installation enables the agent for a specific tenant / property scope (see `agent_installation`). The MCP Registry's `server.json` is the precedent for storing metadata rather than artifacts; AWS Agent Registry's curation + approval workflow is the precedent for the `review_status` gate.", "operationId": "get_hospitality_agent_registry_entry", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_registry_entry" }, "properties": { "additionalProperties": false, "properties": { "agent_key": { "title": "Stable registry key (e.g. `io.github.vendor/recovery-agent`)", "type": "string" }, "declared_action_scopes": { "items": { "type": "string" }, "title": "Maximum action scopes the agent claims it may need", "type": "array" }, "declared_data_classes": { "items": { "enum": [ "public", "operational", "guest_pii", "staff_pii", "payment_metadata", "regulated_health", "secrets" ], "type": "string" }, "title": "Data classes the agent processes", "type": "array" }, "declared_function_scopes": { "items": { "type": "string" }, "title": "Maximum function scopes the agent claims it may need", "type": "array" }, "declared_read_scopes": { "items": { "type": "string" }, "title": "Object types the agent reads, each `objects::read` naming a registered type. The ceiling an installation's `enabled_read_scopes` is held to; empty or absent declares no narrowed read set.", "type": "array" }, "declared_risk_tiers": { "items": { "enum": [ "read_only", "internal_write", "guest_message", "money_movement", "identity_or_fraud", "clinical_or_regulated", "other_high_risk" ], "type": "string" }, "title": "Risk tiers the agent claims it may take steps under", "type": "array" }, "definition_document": { "title": "The runtime-interpreted agent definition (design D3; runtime owns the grammar)" }, "description": { "title": "Bounded to 2048 characters", "type": "string" }, "grounding_scope_ref": { "title": "scope_key of the `grounding_scope` injected into the retrieval lane (D11)", "type": "string" }, "id": { "title": "Registry entry id", "type": "string" }, "mcp_server_uri": { "title": "Canonical remote MCP endpoint when applicable; HTTPS-only enforced by `mcp_remote_requires_https`", "type": "string" }, "model_family": { "title": "Model family when known (e.g. `claude-opus`, `gpt-5`)", "type": "string" }, "model_provider": { "title": "Model provider when known (e.g. `anthropic`, `openai`)", "type": "string" }, "obo_scopes": { "items": { "type": "string" }, "title": "Execute scopes exercisable on behalf of an invoking user (K5 ceiling)", "type": "array" }, "package_references": { "description": "Package or artifact references using the source registry's shape", "items": { "properties": { "digest": { "type": "string" }, "name": { "type": "string" }, "registry_type": { "type": "string" }, "uri": { "type": "string" }, "version": { "type": "string" } }, "required": [ "registry_type", "name" ], "type": "object" }, "title": "Agent registry entry package references", "type": "array" }, "privacy_url": { "title": "Publisher privacy / DPA documentation", "type": "string" }, "protocols": { "items": { "enum": [ "mcp", "openapi", "webhook", "sdk", "a2a", "custom" ], "type": "string" }, "title": "Protocols the agent supports", "type": "array" }, "published_at": { "format": "date-time", "title": "Source publish time", "type": "string" }, "publisher": { "title": "Vendor / publisher namespace", "type": "string" }, "registry_record_uri": { "title": "Source registry URL / ARN / id", "type": "string" }, "registry_source": { "enum": [ "aerandil_first_party", "mcp_registry", "aws_agent_registry", "apaleo_agent_hub", "private_registry", "manual" ], "title": "Origin of this registry entry", "type": "string" }, "review_status": { "enum": [ "submitted", "approved", "rejected", "deprecated", "blocked" ], "title": "Curator review status; only `approved` is installable", "type": "string" }, "reviewed_at": { "format": "date-time", "title": "Review timestamp", "type": "string" }, "reviewed_by": { "title": "Principal stable id of the reviewer", "type": "string" }, "safety_profile": { "title": "Prompt-injection, data handling, human-review, evaluation metadata" }, "security_url": { "title": "Security review / SOC2 / vuln disclosure docs", "type": "string" }, "title": { "title": "Display name", "type": "string" }, "version": { "title": "Agent package / server / skill version", "type": "string" } }, "required": [ "id", "agent_key", "publisher", "version", "title", "registry_source", "protocols", "package_references", "declared_action_scopes", "declared_function_scopes", "declared_data_classes", "declared_risk_tiers", "review_status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.agent_registry_entry:read" ] } ], "summary": "Read Agent registry entry", "tags": [ "agents" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.agent_registry_entry/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nCatalog metadata for a first-party or third-party agent, MCP server, or agent skill. Declares maximum action / function / data-class scopes the agent claims to need plus vendor / model / safety metadata. **A registry entry is not permission to run** — installation enables the agent for a specific tenant / property scope (see `agent_installation`). The MCP Registry's `server.json` is the precedent for storing metadata rather than artifacts; AWS Agent Registry's curation + approval workflow is the precedent for the `review_status` gate.", "operationId": "get_hospitality_agent_registry_entry_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.agent_registry_entry" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.agent_registry_entry:read" ] } ], "summary": "Read Agent registry entry as of a watermark", "tags": [ "agents" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.agent_registry_entry/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nCatalog metadata for a first-party or third-party agent, MCP server, or agent skill. Declares maximum action / function / data-class scopes the agent claims to need plus vendor / model / safety metadata. **A registry entry is not permission to run** — installation enables the agent for a specific tenant / property scope (see `agent_installation`). The MCP Registry's `server.json` is the precedent for storing metadata rather than artifacts; AWS Agent Registry's curation + approval workflow is the precedent for the `review_status` gate.", "operationId": "list_links_hospitality_agent_registry_entry", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.agent_registry_entry:read" ] } ], "summary": "List links of Agent registry entry", "tags": [ "agents" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.agent_installation_for_registry_entry" ] } } ] }, "/v1/object-types/hospitality.agent_registry_entry/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nCatalog metadata for a first-party or third-party agent, MCP server, or agent skill. Declares maximum action / function / data-class scopes the agent claims to need plus vendor / model / safety metadata. **A registry entry is not permission to run** — installation enables the agent for a specific tenant / property scope (see `agent_installation`). The MCP Registry's `server.json` is the precedent for storing metadata rather than artifacts; AWS Agent Registry's curation + approval workflow is the precedent for the `review_status` gate.", "operationId": "traverse_hospitality_agent_registry_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.agent_installation_for_registry_entry" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.agent_registry_entry:read" ] } ], "summary": "Traverse from Agent registry entry", "tags": [ "agents" ] } }, "/v1/object-types/hospitality.agent_registry_entry/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nCatalog metadata for a first-party or third-party agent, MCP server, or agent skill. Declares maximum action / function / data-class scopes the agent claims to need plus vendor / model / safety metadata. **A registry entry is not permission to run** — installation enables the agent for a specific tenant / property scope (see `agent_installation`). The MCP Registry's `server.json` is the precedent for storing metadata rather than artifacts; AWS Agent Registry's curation + approval workflow is the precedent for the `review_status` gate.", "operationId": "search_hospitality_agent_registry_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_key" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_key" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_key" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_key" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "publisher" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "publisher" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "publisher" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "publisher" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "version" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "version" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "version" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "version" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "title" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "title" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "title" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "title" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "registry_source" }, "type": { "const": "eq" }, "value": { "enum": [ "aerandil_first_party", "mcp_registry", "aws_agent_registry", "apaleo_agent_hub", "private_registry", "manual" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "registry_record_uri" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "registry_record_uri" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "registry_record_uri" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "registry_record_uri" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "protocols" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "mcp", "openapi", "webhook", "sdk", "a2a", "custom" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "mcp_server_uri" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "mcp_server_uri" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "mcp_server_uri" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "mcp_server_uri" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "package_references" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "digest": { "type": "string" }, "name": { "type": "string" }, "registry_type": { "type": "string" }, "uri": { "type": "string" }, "version": { "type": "string" } }, "required": [ "registry_type", "name" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "declared_action_scopes" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "declared_function_scopes" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "declared_read_scopes" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "declared_data_classes" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "public", "operational", "guest_pii", "staff_pii", "payment_metadata", "regulated_health", "secrets" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "declared_risk_tiers" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "read_only", "internal_write", "guest_message", "money_movement", "identity_or_fraud", "clinical_or_regulated", "other_high_risk" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_provider" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_provider" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_provider" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_provider" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_family" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_family" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_family" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_family" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "safety_profile" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "privacy_url" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "privacy_url" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "privacy_url" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "privacy_url" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "security_url" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "security_url" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "security_url" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "security_url" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "review_status" }, "type": { "const": "eq" }, "value": { "enum": [ "submitted", "approved", "rejected", "deprecated", "blocked" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reviewed_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reviewed_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reviewed_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reviewed_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reviewed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reviewed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reviewed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "published_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "published_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "published_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_document" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "obo_scopes" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "grounding_scope_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "grounding_scope_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "grounding_scope_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "grounding_scope_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "agent_key", "publisher", "version", "title", "description", "registry_source", "registry_record_uri", "mcp_server_uri", "model_provider", "model_family", "privacy_url", "security_url", "review_status", "reviewed_by", "reviewed_at", "published_at", "grounding_scope_ref" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_registry_entry" }, "properties": { "additionalProperties": false, "properties": { "agent_key": { "title": "Stable registry key (e.g. `io.github.vendor/recovery-agent`)", "type": "string" }, "declared_action_scopes": { "items": { "type": "string" }, "title": "Maximum action scopes the agent claims it may need", "type": "array" }, "declared_data_classes": { "items": { "enum": [ "public", "operational", "guest_pii", "staff_pii", "payment_metadata", "regulated_health", "secrets" ], "type": "string" }, "title": "Data classes the agent processes", "type": "array" }, "declared_function_scopes": { "items": { "type": "string" }, "title": "Maximum function scopes the agent claims it may need", "type": "array" }, "declared_read_scopes": { "items": { "type": "string" }, "title": "Object types the agent reads, each `objects::read` naming a registered type. The ceiling an installation's `enabled_read_scopes` is held to; empty or absent declares no narrowed read set.", "type": "array" }, "declared_risk_tiers": { "items": { "enum": [ "read_only", "internal_write", "guest_message", "money_movement", "identity_or_fraud", "clinical_or_regulated", "other_high_risk" ], "type": "string" }, "title": "Risk tiers the agent claims it may take steps under", "type": "array" }, "definition_document": { "title": "The runtime-interpreted agent definition (design D3; runtime owns the grammar)" }, "description": { "title": "Bounded to 2048 characters", "type": "string" }, "grounding_scope_ref": { "title": "scope_key of the `grounding_scope` injected into the retrieval lane (D11)", "type": "string" }, "id": { "title": "Registry entry id", "type": "string" }, "mcp_server_uri": { "title": "Canonical remote MCP endpoint when applicable; HTTPS-only enforced by `mcp_remote_requires_https`", "type": "string" }, "model_family": { "title": "Model family when known (e.g. `claude-opus`, `gpt-5`)", "type": "string" }, "model_provider": { "title": "Model provider when known (e.g. `anthropic`, `openai`)", "type": "string" }, "obo_scopes": { "items": { "type": "string" }, "title": "Execute scopes exercisable on behalf of an invoking user (K5 ceiling)", "type": "array" }, "package_references": { "description": "Package or artifact references using the source registry's shape", "items": { "properties": { "digest": { "type": "string" }, "name": { "type": "string" }, "registry_type": { "type": "string" }, "uri": { "type": "string" }, "version": { "type": "string" } }, "required": [ "registry_type", "name" ], "type": "object" }, "title": "Agent registry entry package references", "type": "array" }, "privacy_url": { "title": "Publisher privacy / DPA documentation", "type": "string" }, "protocols": { "items": { "enum": [ "mcp", "openapi", "webhook", "sdk", "a2a", "custom" ], "type": "string" }, "title": "Protocols the agent supports", "type": "array" }, "published_at": { "format": "date-time", "title": "Source publish time", "type": "string" }, "publisher": { "title": "Vendor / publisher namespace", "type": "string" }, "registry_record_uri": { "title": "Source registry URL / ARN / id", "type": "string" }, "registry_source": { "enum": [ "aerandil_first_party", "mcp_registry", "aws_agent_registry", "apaleo_agent_hub", "private_registry", "manual" ], "title": "Origin of this registry entry", "type": "string" }, "review_status": { "enum": [ "submitted", "approved", "rejected", "deprecated", "blocked" ], "title": "Curator review status; only `approved` is installable", "type": "string" }, "reviewed_at": { "format": "date-time", "title": "Review timestamp", "type": "string" }, "reviewed_by": { "title": "Principal stable id of the reviewer", "type": "string" }, "safety_profile": { "title": "Prompt-injection, data handling, human-review, evaluation metadata" }, "security_url": { "title": "Security review / SOC2 / vuln disclosure docs", "type": "string" }, "title": { "title": "Display name", "type": "string" }, "version": { "title": "Agent package / server / skill version", "type": "string" } }, "required": [ "id", "agent_key", "publisher", "version", "title", "registry_source", "protocols", "package_references", "declared_action_scopes", "declared_function_scopes", "declared_data_classes", "declared_risk_tiers", "review_status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.agent_registry_entry:read" ] } ], "summary": "Search Agent registry entry", "tags": [ "agents" ] } }, "/v1/object-types/hospitality.agent_thread/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA persistent operator↔agent conversation. Threads are server-side ontology objects (agent-stack design D9): the Explorer agent panel and the agent runtime both read and append through actions, so no client holds private history. `agent_key` names the agent definition the thread converses with; message turns are `agent_thread_message` rows reached via `agent_thread_message_in_thread`. Appends are rejected once `thread_status` is `closed`.", "operationId": "get_hospitality_agent_thread", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_thread" }, "properties": { "additionalProperties": false, "properties": { "agent_key": { "title": "The agent definition this thread converses with", "type": "string" }, "id": { "title": "Thread id", "type": "string" }, "last_message_at": { "format": "date-time", "title": "Most recent turn timestamp (denormalised; refreshed by append)", "type": "string" }, "message_count": { "title": "Count of turns in this thread (denormalised; refreshed by append)", "type": "integer" }, "opened_at": { "format": "date-time", "title": "When the thread opened", "type": "string" }, "opened_by": { "title": "`principal.stable_id()` of the opener", "type": "string" }, "subject": { "title": "Display subject (defaults to the opening task's first line)", "type": "string" }, "thread_status": { "enum": [ "open", "closed" ], "title": "Lifecycle state", "type": "string" } }, "required": [ "id", "agent_key", "thread_status", "opened_at", "last_message_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.agent_thread:read" ] } ], "summary": "Read Agent thread", "tags": [ "agents" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.agent_thread/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA persistent operator↔agent conversation. Threads are server-side ontology objects (agent-stack design D9): the Explorer agent panel and the agent runtime both read and append through actions, so no client holds private history. `agent_key` names the agent definition the thread converses with; message turns are `agent_thread_message` rows reached via `agent_thread_message_in_thread`. Appends are rejected once `thread_status` is `closed`.", "operationId": "get_hospitality_agent_thread_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.agent_thread" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.agent_thread:read" ] } ], "summary": "Read Agent thread as of a watermark", "tags": [ "agents" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.agent_thread/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA persistent operator↔agent conversation. Threads are server-side ontology objects (agent-stack design D9): the Explorer agent panel and the agent runtime both read and append through actions, so no client holds private history. `agent_key` names the agent definition the thread converses with; message turns are `agent_thread_message` rows reached via `agent_thread_message_in_thread`. Appends are rejected once `thread_status` is `closed`.", "operationId": "list_links_hospitality_agent_thread", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.agent_thread:read" ] } ], "summary": "List links of Agent thread", "tags": [ "agents" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.agent_thread_message_in_thread" ] } } ] }, "/v1/object-types/hospitality.agent_thread/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA persistent operator↔agent conversation. Threads are server-side ontology objects (agent-stack design D9): the Explorer agent panel and the agent runtime both read and append through actions, so no client holds private history. `agent_key` names the agent definition the thread converses with; message turns are `agent_thread_message` rows reached via `agent_thread_message_in_thread`. Appends are rejected once `thread_status` is `closed`.", "operationId": "traverse_hospitality_agent_thread", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.agent_thread_message_in_thread" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.agent_thread:read" ] } ], "summary": "Traverse from Agent thread", "tags": [ "agents" ] } }, "/v1/object-types/hospitality.agent_thread/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA persistent operator↔agent conversation. Threads are server-side ontology objects (agent-stack design D9): the Explorer agent panel and the agent runtime both read and append through actions, so no client holds private history. `agent_key` names the agent definition the thread converses with; message turns are `agent_thread_message` rows reached via `agent_thread_message_in_thread`. Appends are rejected once `thread_status` is `closed`.", "operationId": "search_hospitality_agent_thread", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_key" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_key" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_key" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_key" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "subject" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "subject" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "subject" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "subject" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "thread_status" }, "type": { "const": "eq" }, "value": { "enum": [ "open", "closed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_message_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_message_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_message_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "message_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "message_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "message_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "agent_key", "subject", "thread_status", "opened_by", "opened_at", "last_message_at", "message_count" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_thread" }, "properties": { "additionalProperties": false, "properties": { "agent_key": { "title": "The agent definition this thread converses with", "type": "string" }, "id": { "title": "Thread id", "type": "string" }, "last_message_at": { "format": "date-time", "title": "Most recent turn timestamp (denormalised; refreshed by append)", "type": "string" }, "message_count": { "title": "Count of turns in this thread (denormalised; refreshed by append)", "type": "integer" }, "opened_at": { "format": "date-time", "title": "When the thread opened", "type": "string" }, "opened_by": { "title": "`principal.stable_id()` of the opener", "type": "string" }, "subject": { "title": "Display subject (defaults to the opening task's first line)", "type": "string" }, "thread_status": { "enum": [ "open", "closed" ], "title": "Lifecycle state", "type": "string" } }, "required": [ "id", "agent_key", "thread_status", "opened_at", "last_message_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.agent_thread:read" ] } ], "summary": "Search Agent thread", "tags": [ "agents" ] } }, "/v1/object-types/hospitality.agent_thread_message/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne turn in an `agent_thread` — a `user` task or the agent's final reply. The full step sequence behind an `agent` turn (tool calls, usage, deltas) is the trace store's business, reached via `session_id`; the thread keeps only what a conversation replay needs. `parent_message_ref` makes threads branchable (the Snowflake parent-pointer pattern). Immutable once appended.", "operationId": "get_hospitality_agent_thread_message", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_thread_message" }, "properties": { "additionalProperties": false, "properties": { "authored_at": { "format": "date-time", "title": "When the turn was appended", "type": "string" }, "authored_by": { "title": "`principal.stable_id()` of the author", "type": "string" }, "content": { "title": "The turn's text", "type": "string" }, "id": { "title": "Message id", "type": "string" }, "parent_message_ref": { "format": "uuid", "title": "Branch parent (omitted = continues the latest turn)", "type": "string", "x-aerandil-references": "hospitality.agent_thread_message" }, "role": { "enum": [ "user", "agent" ], "title": "Who authored this turn", "type": "string" }, "session_id": { "title": "The runtime session (trace) that produced an `agent` turn", "type": "string" }, "thread_ref": { "format": "uuid", "title": "The containing thread", "type": "string", "x-aerandil-references": "hospitality.agent_thread" } }, "required": [ "id", "thread_ref", "role", "authored_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.agent_thread_message:read" ] } ], "summary": "Read Agent thread message", "tags": [ "agents" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.agent_thread_message/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne turn in an `agent_thread` — a `user` task or the agent's final reply. The full step sequence behind an `agent` turn (tool calls, usage, deltas) is the trace store's business, reached via `session_id`; the thread keeps only what a conversation replay needs. `parent_message_ref` makes threads branchable (the Snowflake parent-pointer pattern). Immutable once appended.", "operationId": "get_hospitality_agent_thread_message_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.agent_thread_message" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.agent_thread_message:read" ] } ], "summary": "Read Agent thread message as of a watermark", "tags": [ "agents" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.agent_thread_message/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne turn in an `agent_thread` — a `user` task or the agent's final reply. The full step sequence behind an `agent` turn (tool calls, usage, deltas) is the trace store's business, reached via `session_id`; the thread keeps only what a conversation replay needs. `parent_message_ref` makes threads branchable (the Snowflake parent-pointer pattern). Immutable once appended.", "operationId": "list_links_hospitality_agent_thread_message", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.agent_thread_message:read" ] } ], "summary": "List links of Agent thread message", "tags": [ "agents" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.agent_thread_message_in_thread" ] } } ] }, "/v1/object-types/hospitality.agent_thread_message/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne turn in an `agent_thread` — a `user` task or the agent's final reply. The full step sequence behind an `agent` turn (tool calls, usage, deltas) is the trace store's business, reached via `session_id`; the thread keeps only what a conversation replay needs. `parent_message_ref` makes threads branchable (the Snowflake parent-pointer pattern). Immutable once appended.", "operationId": "traverse_hospitality_agent_thread_message", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.agent_thread_message_in_thread" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.agent_thread_message:read" ] } ], "summary": "Traverse from Agent thread message", "tags": [ "agents" ] } }, "/v1/object-types/hospitality.agent_thread_message/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne turn in an `agent_thread` — a `user` task or the agent's final reply. The full step sequence behind an `agent` turn (tool calls, usage, deltas) is the trace store's business, reached via `session_id`; the thread keeps only what a conversation replay needs. `parent_message_ref` makes threads branchable (the Snowflake parent-pointer pattern). Immutable once appended.", "operationId": "search_hospitality_agent_thread_message", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "thread_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.agent_thread" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "role" }, "type": { "const": "eq" }, "value": { "enum": [ "user", "agent" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "content" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "content" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "parent_message_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.agent_thread_message" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "session_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "session_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "session_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "session_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authored_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authored_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authored_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authored_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authored_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authored_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authored_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "role", "content", "session_id", "authored_by", "authored_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.agent_thread_message" }, "properties": { "additionalProperties": false, "properties": { "authored_at": { "format": "date-time", "title": "When the turn was appended", "type": "string" }, "authored_by": { "title": "`principal.stable_id()` of the author", "type": "string" }, "content": { "title": "The turn's text", "type": "string" }, "id": { "title": "Message id", "type": "string" }, "parent_message_ref": { "format": "uuid", "title": "Branch parent (omitted = continues the latest turn)", "type": "string", "x-aerandil-references": "hospitality.agent_thread_message" }, "role": { "enum": [ "user", "agent" ], "title": "Who authored this turn", "type": "string" }, "session_id": { "title": "The runtime session (trace) that produced an `agent` turn", "type": "string" }, "thread_ref": { "format": "uuid", "title": "The containing thread", "type": "string", "x-aerandil-references": "hospitality.agent_thread" } }, "required": [ "id", "thread_ref", "role", "authored_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.agent_thread_message:read" ] } ], "summary": "Search Agent thread message", "tags": [ "agents" ] } }, "/v1/object-types/hospitality.allergy_alert/objects/{id}": { "get": { "description": "Read an existing instance.\n\nPerson-attached structured record of a single food allergy: which EU 1169/2011-listed allergen (matching `recipe.allergens` so menu↔guest joins are trivial), how severe the documented reaction, how confident the diagnosis (self-reported → oral food challenge), and what the kitchen / front-of-house protocol should be. One alert per (person, allergen); persons with multiple allergies carry multiple alert rows. Pairs with `recipe.allergens` / `recipe_ingredient.allergen_flags` on the producer side and with `external_record_reference` on the clinical-record seam (Aerandil never carries the underlying diagnostic payload — see `external_records.rs`). The free-text `dietary` field on `person.preferences` is consumer-side lifestyle (vegan, kosher); allergen alerts live here so the medical surface stays structured.", "operationId": "get_hospitality_allergy_alert", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.allergy_alert" }, "properties": { "additionalProperties": false, "properties": { "airborne_sensitive": { "title": "Reaction possible from cooking vapour / particulate", "type": "boolean" }, "allergen": { "enum": [ "gluten", "crustaceans", "eggs", "fish", "peanuts", "soybeans", "milk", "nuts", "celery", "mustard", "sesame", "sulphites", "lupin", "molluscs" ], "title": "Allergen (EU 1169/2011 Annex II vocabulary)", "type": "string" }, "clinical_status": { "enum": [ "self_reported", "family_reported", "clinician_diagnosed", "skin_prick_confirmed", "specific_ige_confirmed", "oral_food_challenge_confirmed" ], "title": "Diagnosis provenance", "type": "string" }, "cross_contact_sensitive": { "title": "Kitchen must use separate equipment / surfaces", "type": "boolean" }, "diagnosed_on": { "format": "date", "title": "Diagnosis date", "type": "string" }, "emergency_action_plan_text": { "title": "Operator-readable action plan (free text — clinical plan stays in `clinical_record_ref`)", "type": "string" }, "epi_pen_required": { "title": "Epinephrine on-person required (paired with severity ∈ {severe, life_threatening})", "type": "boolean" }, "expires_on": { "format": "date", "title": "When the alert becomes inactive (childhood allergies can be outgrown; null = no expiry)", "type": "string" }, "id": { "title": "Alert id", "type": "string" }, "last_verified_on": { "format": "date", "title": "When the operator last re-confirmed the alert with the person", "type": "string" }, "notes": { "title": "Operator notes (front-of-house phrasing, prior-incident references)", "type": "string" }, "severity": { "enum": [ "intolerance", "mild", "moderate", "severe", "life_threatening" ], "title": "Severity (operator-facing five-rung ladder)", "type": "string" } }, "required": [ "id" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.allergy_alert:read" ] } ], "summary": "Read Allergy alert", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.allergy_alert/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nPerson-attached structured record of a single food allergy: which EU 1169/2011-listed allergen (matching `recipe.allergens` so menu↔guest joins are trivial), how severe the documented reaction, how confident the diagnosis (self-reported → oral food challenge), and what the kitchen / front-of-house protocol should be. One alert per (person, allergen); persons with multiple allergies carry multiple alert rows. Pairs with `recipe.allergens` / `recipe_ingredient.allergen_flags` on the producer side and with `external_record_reference` on the clinical-record seam (Aerandil never carries the underlying diagnostic payload — see `external_records.rs`). The free-text `dietary` field on `person.preferences` is consumer-side lifestyle (vegan, kosher); allergen alerts live here so the medical surface stays structured.", "operationId": "get_hospitality_allergy_alert_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.allergy_alert" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.allergy_alert:read" ] } ], "summary": "Read Allergy alert as of a watermark", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.allergy_alert/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nPerson-attached structured record of a single food allergy: which EU 1169/2011-listed allergen (matching `recipe.allergens` so menu↔guest joins are trivial), how severe the documented reaction, how confident the diagnosis (self-reported → oral food challenge), and what the kitchen / front-of-house protocol should be. One alert per (person, allergen); persons with multiple allergies carry multiple alert rows. Pairs with `recipe.allergens` / `recipe_ingredient.allergen_flags` on the producer side and with `external_record_reference` on the clinical-record seam (Aerandil never carries the underlying diagnostic payload — see `external_records.rs`). The free-text `dietary` field on `person.preferences` is consumer-side lifestyle (vegan, kosher); allergen alerts live here so the medical surface stays structured.", "operationId": "list_links_hospitality_allergy_alert", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.allergy_alert:read" ] } ], "summary": "List links of Allergy alert", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.allergy_alert_for_person", "hospitality.link.allergy_alert_references_external_record" ] } } ] }, "/v1/object-types/hospitality.allergy_alert/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nPerson-attached structured record of a single food allergy: which EU 1169/2011-listed allergen (matching `recipe.allergens` so menu↔guest joins are trivial), how severe the documented reaction, how confident the diagnosis (self-reported → oral food challenge), and what the kitchen / front-of-house protocol should be. One alert per (person, allergen); persons with multiple allergies carry multiple alert rows. Pairs with `recipe.allergens` / `recipe_ingredient.allergen_flags` on the producer side and with `external_record_reference` on the clinical-record seam (Aerandil never carries the underlying diagnostic payload — see `external_records.rs`). The free-text `dietary` field on `person.preferences` is consumer-side lifestyle (vegan, kosher); allergen alerts live here so the medical surface stays structured.", "operationId": "traverse_hospitality_allergy_alert", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.allergy_alert_for_person", "hospitality.link.allergy_alert_references_external_record" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.allergy_alert:read" ] } ], "summary": "Traverse from Allergy alert", "tags": [ "people" ] } }, "/v1/object-types/hospitality.allergy_alert/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nPerson-attached structured record of a single food allergy: which EU 1169/2011-listed allergen (matching `recipe.allergens` so menu↔guest joins are trivial), how severe the documented reaction, how confident the diagnosis (self-reported → oral food challenge), and what the kitchen / front-of-house protocol should be. One alert per (person, allergen); persons with multiple allergies carry multiple alert rows. Pairs with `recipe.allergens` / `recipe_ingredient.allergen_flags` on the producer side and with `external_record_reference` on the clinical-record seam (Aerandil never carries the underlying diagnostic payload — see `external_records.rs`). The free-text `dietary` field on `person.preferences` is consumer-side lifestyle (vegan, kosher); allergen alerts live here so the medical surface stays structured.", "operationId": "search_hospitality_allergy_alert", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "allergen" }, "type": { "const": "eq" }, "value": { "enum": [ "gluten", "crustaceans", "eggs", "fish", "peanuts", "soybeans", "milk", "nuts", "celery", "mustard", "sesame", "sulphites", "lupin", "molluscs" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "severity" }, "type": { "const": "eq" }, "value": { "enum": [ "intolerance", "mild", "moderate", "severe", "life_threatening" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "clinical_status" }, "type": { "const": "eq" }, "value": { "enum": [ "self_reported", "family_reported", "clinician_diagnosed", "skin_prick_confirmed", "specific_ige_confirmed", "oral_food_challenge_confirmed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cross_contact_sensitive" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "airborne_sensitive" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "epi_pen_required" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "emergency_action_plan_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "emergency_action_plan_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "diagnosed_on" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "diagnosed_on" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "diagnosed_on" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_verified_on" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_verified_on" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_verified_on" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_on" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_on" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_on" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "allergen", "severity", "clinical_status", "emergency_action_plan_text", "diagnosed_on", "last_verified_on", "expires_on", "notes" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.allergy_alert" }, "properties": { "additionalProperties": false, "properties": { "airborne_sensitive": { "title": "Reaction possible from cooking vapour / particulate", "type": "boolean" }, "allergen": { "enum": [ "gluten", "crustaceans", "eggs", "fish", "peanuts", "soybeans", "milk", "nuts", "celery", "mustard", "sesame", "sulphites", "lupin", "molluscs" ], "title": "Allergen (EU 1169/2011 Annex II vocabulary)", "type": "string" }, "clinical_status": { "enum": [ "self_reported", "family_reported", "clinician_diagnosed", "skin_prick_confirmed", "specific_ige_confirmed", "oral_food_challenge_confirmed" ], "title": "Diagnosis provenance", "type": "string" }, "cross_contact_sensitive": { "title": "Kitchen must use separate equipment / surfaces", "type": "boolean" }, "diagnosed_on": { "format": "date", "title": "Diagnosis date", "type": "string" }, "emergency_action_plan_text": { "title": "Operator-readable action plan (free text — clinical plan stays in `clinical_record_ref`)", "type": "string" }, "epi_pen_required": { "title": "Epinephrine on-person required (paired with severity ∈ {severe, life_threatening})", "type": "boolean" }, "expires_on": { "format": "date", "title": "When the alert becomes inactive (childhood allergies can be outgrown; null = no expiry)", "type": "string" }, "id": { "title": "Alert id", "type": "string" }, "last_verified_on": { "format": "date", "title": "When the operator last re-confirmed the alert with the person", "type": "string" }, "notes": { "title": "Operator notes (front-of-house phrasing, prior-incident references)", "type": "string" }, "severity": { "enum": [ "intolerance", "mild", "moderate", "severe", "life_threatening" ], "title": "Severity (operator-facing five-rung ladder)", "type": "string" } }, "required": [ "id" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.allergy_alert:read" ] } ], "summary": "Search Allergy alert", "tags": [ "people" ] } }, "/v1/object-types/hospitality.appointment/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA timed-service booking: one guest × one service in a time window, with the price and buffer pair snapshotted from the spa_service at booking. Lifecycle: booked → confirmed → checked_in → in_service → completed → settled, with cancelled / no_show off-ramps — mutates only through the nine spa actions. `booked_at` is the business instant the booking was taken (pace and lead-time reads derive from it, the reservation discipline); `start_at`/`end_at` bound the treatment itself, and room occupancy extends to [start_at - pre_time, end_at + cleanup_time]. settle_appointment is settle_check's twin: a room_charge tender posts one aggregated folio charge; every tender emits the enriched spa.appointment_settled event, which is the revenue row for card/cash walk-ins (no folio is minted for a POS sale).", "operationId": "get_hospitality_appointment", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" }, "properties": { "additionalProperties": false, "properties": { "booked_at": { "format": "date-time", "title": "When the booking was taken (business time — pace/lead-time reads)", "type": "string" }, "booked_by": { "title": "Principal::stable_id() of the booking principal", "type": "string" }, "cancellation_kind": { "enum": [ "guest", "late", "operator" ], "title": "Cancellation kind (required when cancelled; absent on no_show)", "type": "string" }, "cancelled_at": { "format": "date-time", "title": "When the appointment was cancelled or marked no-show", "type": "string" }, "checked_in_at": { "format": "date-time", "title": "When the guest arrived at the spa desk", "type": "string" }, "cleanup_time_minutes": { "title": "Turnover buffer snapshotted from the service at booking", "type": "integer" }, "completed_at": { "format": "date-time", "title": "When the treatment ended", "type": "string" }, "confirmed_at": { "format": "date-time", "title": "When the guest reconfirmed", "type": "string" }, "end_at": { "format": "date-time", "title": "Treatment end (start + service duration at booking)", "type": "string" }, "external_ref": { "title": "Source-system key for replayed / connector-landed bookings", "type": "string" }, "gratuity": { "description": "Voluntary gratuity added at settle (pass-through, not department revenue)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Appointment gratuity", "type": "object" }, "guest_kind": { "enum": [ "hotel_guest", "member", "external" ], "title": "Who the client is to the property (in-house capture dimension)", "type": "string" }, "id": { "title": "Appointment id", "type": "string" }, "notes": { "title": "Front-desk / therapist notes (may carry intake detail)", "type": "string" }, "pre_time_minutes": { "title": "Setup buffer snapshotted from the service at booking", "type": "integer" }, "price": { "description": "Price snapshotted from the service at booking", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Appointment price", "type": "object" }, "service_started_at": { "format": "date-time", "title": "When the treatment actually began", "type": "string" }, "settled_at": { "format": "date-time", "title": "When the appointment settled", "type": "string" }, "settlement_reference": { "title": "PSP / drawer / platform reference for non-room tenders", "type": "string" }, "start_at": { "format": "date-time", "title": "Treatment start", "type": "string" }, "status": { "enum": [ "booked", "confirmed", "checked_in", "in_service", "completed", "settled", "cancelled", "no_show" ], "title": "Appointment lifecycle status", "type": "string" }, "tender": { "enum": [ "room_charge", "cash", "card", "comp", "external", "charge_to_key" ], "title": "Settlement tender (absent until settle; shares the check vocabulary)", "type": "string" } }, "required": [ "id", "status", "start_at", "end_at", "pre_time_minutes", "cleanup_time_minutes", "price", "booked_at", "booked_by" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.appointment:read" ] } ], "summary": "Read Appointment", "tags": [ "spa" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.appointment/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA timed-service booking: one guest × one service in a time window, with the price and buffer pair snapshotted from the spa_service at booking. Lifecycle: booked → confirmed → checked_in → in_service → completed → settled, with cancelled / no_show off-ramps — mutates only through the nine spa actions. `booked_at` is the business instant the booking was taken (pace and lead-time reads derive from it, the reservation discipline); `start_at`/`end_at` bound the treatment itself, and room occupancy extends to [start_at - pre_time, end_at + cleanup_time]. settle_appointment is settle_check's twin: a room_charge tender posts one aggregated folio charge; every tender emits the enriched spa.appointment_settled event, which is the revenue row for card/cash walk-ins (no folio is minted for a POS sale).", "operationId": "get_hospitality_appointment_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.appointment" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.appointment:read" ] } ], "summary": "Read Appointment as of a watermark", "tags": [ "spa" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.appointment/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA timed-service booking: one guest × one service in a time window, with the price and buffer pair snapshotted from the spa_service at booking. Lifecycle: booked → confirmed → checked_in → in_service → completed → settled, with cancelled / no_show off-ramps — mutates only through the nine spa actions. `booked_at` is the business instant the booking was taken (pace and lead-time reads derive from it, the reservation discipline); `start_at`/`end_at` bound the treatment itself, and room occupancy extends to [start_at - pre_time, end_at + cleanup_time]. settle_appointment is settle_check's twin: a room_charge tender posts one aggregated folio charge; every tender emits the enriched spa.appointment_settled event, which is the revenue row for card/cash walk-ins (no folio is minted for a POS sale).", "operationId": "list_links_hospitality_appointment", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.appointment:read" ] } ], "summary": "List links of Appointment", "tags": [ "spa" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.appointment_at_outlet", "hospitality.link.appointment_for_person", "hospitality.link.appointment_for_service", "hospitality.link.appointment_in_treatment_room", "hospitality.link.appointment_references_external_record", "hospitality.link.appointment_settled_to_folio", "hospitality.link.appointment_with_provider" ] } } ] }, "/v1/object-types/hospitality.appointment/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA timed-service booking: one guest × one service in a time window, with the price and buffer pair snapshotted from the spa_service at booking. Lifecycle: booked → confirmed → checked_in → in_service → completed → settled, with cancelled / no_show off-ramps — mutates only through the nine spa actions. `booked_at` is the business instant the booking was taken (pace and lead-time reads derive from it, the reservation discipline); `start_at`/`end_at` bound the treatment itself, and room occupancy extends to [start_at - pre_time, end_at + cleanup_time]. settle_appointment is settle_check's twin: a room_charge tender posts one aggregated folio charge; every tender emits the enriched spa.appointment_settled event, which is the revenue row for card/cash walk-ins (no folio is minted for a POS sale).", "operationId": "traverse_hospitality_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.appointment_at_outlet", "hospitality.link.appointment_for_person", "hospitality.link.appointment_for_service", "hospitality.link.appointment_in_treatment_room", "hospitality.link.appointment_references_external_record", "hospitality.link.appointment_settled_to_folio", "hospitality.link.appointment_with_provider" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.appointment:read" ] } ], "summary": "Traverse from Appointment", "tags": [ "spa" ] } }, "/v1/object-types/hospitality.appointment/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA timed-service booking: one guest × one service in a time window, with the price and buffer pair snapshotted from the spa_service at booking. Lifecycle: booked → confirmed → checked_in → in_service → completed → settled, with cancelled / no_show off-ramps — mutates only through the nine spa actions. `booked_at` is the business instant the booking was taken (pace and lead-time reads derive from it, the reservation discipline); `start_at`/`end_at` bound the treatment itself, and room occupancy extends to [start_at - pre_time, end_at + cleanup_time]. settle_appointment is settle_check's twin: a room_charge tender posts one aggregated folio charge; every tender emits the enriched spa.appointment_settled event, which is the revenue row for card/cash walk-ins (no folio is minted for a POS sale).", "operationId": "search_hospitality_appointment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "booked", "confirmed", "checked_in", "in_service", "completed", "settled", "cancelled", "no_show" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "start_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "start_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "start_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "end_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "end_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "end_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "pre_time_minutes" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "pre_time_minutes" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "pre_time_minutes" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cleanup_time_minutes" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cleanup_time_minutes" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cleanup_time_minutes" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "price" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "booked_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "booked_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "booked_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "booked_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "booked_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "booked_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "booked_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "guest_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "hotel_guest", "member", "external" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confirmed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confirmed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confirmed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checked_in_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checked_in_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checked_in_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "service_started_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "service_started_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "service_started_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "settled_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "settled_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "settled_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancelled_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancelled_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancelled_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "guest", "late", "operator" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tender" }, "type": { "const": "eq" }, "value": { "enum": [ "room_charge", "cash", "card", "comp", "external", "charge_to_key" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "settlement_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "settlement_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "settlement_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "settlement_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "gratuity" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "status", "start_at", "end_at", "pre_time_minutes", "cleanup_time_minutes", "booked_at", "booked_by", "guest_kind", "confirmed_at", "checked_in_at", "service_started_at", "completed_at", "settled_at", "cancelled_at", "cancellation_kind", "tender", "settlement_reference", "notes", "external_ref" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.appointment" }, "properties": { "additionalProperties": false, "properties": { "booked_at": { "format": "date-time", "title": "When the booking was taken (business time — pace/lead-time reads)", "type": "string" }, "booked_by": { "title": "Principal::stable_id() of the booking principal", "type": "string" }, "cancellation_kind": { "enum": [ "guest", "late", "operator" ], "title": "Cancellation kind (required when cancelled; absent on no_show)", "type": "string" }, "cancelled_at": { "format": "date-time", "title": "When the appointment was cancelled or marked no-show", "type": "string" }, "checked_in_at": { "format": "date-time", "title": "When the guest arrived at the spa desk", "type": "string" }, "cleanup_time_minutes": { "title": "Turnover buffer snapshotted from the service at booking", "type": "integer" }, "completed_at": { "format": "date-time", "title": "When the treatment ended", "type": "string" }, "confirmed_at": { "format": "date-time", "title": "When the guest reconfirmed", "type": "string" }, "end_at": { "format": "date-time", "title": "Treatment end (start + service duration at booking)", "type": "string" }, "external_ref": { "title": "Source-system key for replayed / connector-landed bookings", "type": "string" }, "gratuity": { "description": "Voluntary gratuity added at settle (pass-through, not department revenue)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Appointment gratuity", "type": "object" }, "guest_kind": { "enum": [ "hotel_guest", "member", "external" ], "title": "Who the client is to the property (in-house capture dimension)", "type": "string" }, "id": { "title": "Appointment id", "type": "string" }, "notes": { "title": "Front-desk / therapist notes (may carry intake detail)", "type": "string" }, "pre_time_minutes": { "title": "Setup buffer snapshotted from the service at booking", "type": "integer" }, "price": { "description": "Price snapshotted from the service at booking", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Appointment price", "type": "object" }, "service_started_at": { "format": "date-time", "title": "When the treatment actually began", "type": "string" }, "settled_at": { "format": "date-time", "title": "When the appointment settled", "type": "string" }, "settlement_reference": { "title": "PSP / drawer / platform reference for non-room tenders", "type": "string" }, "start_at": { "format": "date-time", "title": "Treatment start", "type": "string" }, "status": { "enum": [ "booked", "confirmed", "checked_in", "in_service", "completed", "settled", "cancelled", "no_show" ], "title": "Appointment lifecycle status", "type": "string" }, "tender": { "enum": [ "room_charge", "cash", "card", "comp", "external", "charge_to_key" ], "title": "Settlement tender (absent until settle; shares the check vocabulary)", "type": "string" } }, "required": [ "id", "status", "start_at", "end_at", "pre_time_minutes", "cleanup_time_minutes", "price", "booked_at", "booked_by" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.appointment:read" ] } ], "summary": "Search Appointment", "tags": [ "spa" ] } }, "/v1/object-types/hospitality.approval_decision/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne approver's decision on an approval gate. `decided_by` uses `Principal::stable_id()` for humans, services, and agents alike. Agent decisions are recorded for audit but cannot satisfy human-required gates. Supersession is on the `approval_decision_supersedes_decision` self-link, not an inline UUID — the same discipline the rest of the schema uses for supersedence (proposal §4.5 / §6).", "operationId": "get_hospitality_approval_decision", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.approval_decision" }, "properties": { "additionalProperties": false, "properties": { "context_hash": { "title": "Must match the gate context hash unless recording stale evidence", "type": "string" }, "counts_toward_approval": { "title": "False for agent approvals and other audit-only decisions", "type": "boolean" }, "decided_at": { "format": "date-time", "title": "Decision timestamp", "type": "string" }, "decided_by": { "title": "Principal::stable_id() of the decider (human / service / agent)", "type": "string" }, "decider_principal_kind": { "title": "Principal kind snapshot at decision time (system / user / service / agent)", "type": "string" }, "decision": { "enum": [ "approve", "reject", "request_changes", "delegate", "abstain" ], "title": "Decision value recorded by the approver", "type": "string" }, "decision_note": { "title": "Bounded to 1024 characters", "type": "string" }, "external_reference": { "title": "Slack interaction id, Linear comment id, etc.", "type": "string" }, "id": { "title": "Decision id", "type": "string" } }, "required": [ "id", "decision", "decider_principal_kind", "counts_toward_approval", "decided_at", "context_hash" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.approval_decision:read" ] } ], "summary": "Read Approval decision", "tags": [ "approvals" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.approval_decision/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne approver's decision on an approval gate. `decided_by` uses `Principal::stable_id()` for humans, services, and agents alike. Agent decisions are recorded for audit but cannot satisfy human-required gates. Supersession is on the `approval_decision_supersedes_decision` self-link, not an inline UUID — the same discipline the rest of the schema uses for supersedence (proposal §4.5 / §6).", "operationId": "get_hospitality_approval_decision_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.approval_decision" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.approval_decision:read" ] } ], "summary": "Read Approval decision as of a watermark", "tags": [ "approvals" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.approval_decision/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne approver's decision on an approval gate. `decided_by` uses `Principal::stable_id()` for humans, services, and agents alike. Agent decisions are recorded for audit but cannot satisfy human-required gates. Supersession is on the `approval_decision_supersedes_decision` self-link, not an inline UUID — the same discipline the rest of the schema uses for supersedence (proposal §4.5 / §6).", "operationId": "list_links_hospitality_approval_decision", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.approval_decision:read" ] } ], "summary": "List links of Approval decision", "tags": [ "approvals" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.approval_decision_for_gate", "hospitality.link.approval_decision_supersedes_decision" ] } } ] }, "/v1/object-types/hospitality.approval_decision/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne approver's decision on an approval gate. `decided_by` uses `Principal::stable_id()` for humans, services, and agents alike. Agent decisions are recorded for audit but cannot satisfy human-required gates. Supersession is on the `approval_decision_supersedes_decision` self-link, not an inline UUID — the same discipline the rest of the schema uses for supersedence (proposal §4.5 / §6).", "operationId": "traverse_hospitality_approval_decision", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.approval_decision_for_gate", "hospitality.link.approval_decision_supersedes_decision" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.approval_decision:read" ] } ], "summary": "Traverse from Approval decision", "tags": [ "approvals" ] } }, "/v1/object-types/hospitality.approval_decision/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne approver's decision on an approval gate. `decided_by` uses `Principal::stable_id()` for humans, services, and agents alike. Agent decisions are recorded for audit but cannot satisfy human-required gates. Supersession is on the `approval_decision_supersedes_decision` self-link, not an inline UUID — the same discipline the rest of the schema uses for supersedence (proposal §4.5 / §6).", "operationId": "search_hospitality_approval_decision", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decision" }, "type": { "const": "eq" }, "value": { "enum": [ "approve", "reject", "request_changes", "delegate", "abstain" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decider_principal_kind" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decider_principal_kind" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decider_principal_kind" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decider_principal_kind" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "counts_toward_approval" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decision_note" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decision_note" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "context_hash" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "context_hash" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "context_hash" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "context_hash" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "decision", "decided_by", "decider_principal_kind", "decided_at", "decision_note", "context_hash", "external_reference" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.approval_decision" }, "properties": { "additionalProperties": false, "properties": { "context_hash": { "title": "Must match the gate context hash unless recording stale evidence", "type": "string" }, "counts_toward_approval": { "title": "False for agent approvals and other audit-only decisions", "type": "boolean" }, "decided_at": { "format": "date-time", "title": "Decision timestamp", "type": "string" }, "decided_by": { "title": "Principal::stable_id() of the decider (human / service / agent)", "type": "string" }, "decider_principal_kind": { "title": "Principal kind snapshot at decision time (system / user / service / agent)", "type": "string" }, "decision": { "enum": [ "approve", "reject", "request_changes", "delegate", "abstain" ], "title": "Decision value recorded by the approver", "type": "string" }, "decision_note": { "title": "Bounded to 1024 characters", "type": "string" }, "external_reference": { "title": "Slack interaction id, Linear comment id, etc.", "type": "string" }, "id": { "title": "Decision id", "type": "string" } }, "required": [ "id", "decision", "decider_principal_kind", "counts_toward_approval", "decided_at", "context_hash" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.approval_decision:read" ] } ], "summary": "Search Approval decision", "tags": [ "approvals" ] } }, "/v1/object-types/hospitality.approval_gate/objects/{id}": { "get": { "description": "Read an existing instance.\n\nDurable approval gate. Carries an `approval_strategy`, eligible principals / role refs, a `context_snapshot` of the facts shown to approvers, and a `context_hash` over the §4.4.2 input set. Material drift on the underlying parameters, prior outputs, or policy invalidates the gate via `workflow_step_context_hash_stable`. Gates can be used standalone for single-action approvals or attached to a workflow step via `approval_gate_for_workflow_step_run`.", "operationId": "get_hospitality_approval_gate", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.approval_gate" }, "properties": { "additionalProperties": false, "properties": { "approval_strategy": { "enum": [ "any_one", "all", "quorum", "role_based", "ordered_chain", "separation_of_duties" ], "title": "How the gate combines decisions to reach `approved`", "type": "string" }, "assigned_to": { "items": { "type": "string" }, "title": "Current assignees, if narrowed", "type": "array" }, "context_hash": { "title": "Canonical JCS+SHA-256 over the §4.4.2 input set", "type": "string" }, "context_snapshot": { "title": "Frozen, redacted facts shown to approvers" }, "decided_at": { "format": "date-time", "title": "Final decision time", "type": "string" }, "decision_summary": { "title": "Final bounded summary", "type": "string" }, "eligible_principal_ids": { "items": { "type": "string" }, "title": "Exact eligible principals when known (Principal::stable_id() shape)", "type": "array" }, "eligible_role_refs": { "items": { "type": "string" }, "title": "Staff roles / groups that may approve", "type": "array" }, "excluded_principal_ids": { "items": { "type": "string" }, "title": "Requesting agent / author / conflicted principals", "type": "array" }, "expires_at": { "format": "date-time", "title": "Gate timeout", "type": "string" }, "external_reference": { "title": "Slack ts, Linear issue id, PMS task id, email thread id, etc.", "type": "string" }, "gate_key": { "title": "Stable within the workflow run or action correlation id", "type": "string" }, "id": { "title": "Gate id", "type": "string" }, "notification_target": { "enum": [ "in_product", "slack", "linear", "email", "pms_task", "webhook", "other" ], "title": "Where the gate notification surfaced", "type": "string" }, "notified_at": { "format": "date-time", "title": "First notification sent", "type": "string" }, "opened_at": { "format": "date-time", "title": "First in-product open/view event when known", "type": "string" }, "requested_at": { "format": "date-time", "title": "Gate creation", "type": "string" }, "requested_by": { "title": "Principal stable id of the gate requester", "type": "string" }, "required_approval_count": { "title": "Required for `approval_strategy = quorum`", "type": "integer" }, "risk_tier": { "enum": [ "read_only", "internal_write", "guest_message", "money_movement", "identity_or_fraud", "clinical_or_regulated", "other_high_risk" ], "title": "Copied from guarded step / action; drives high-risk policy validators", "type": "string" }, "stale_on_context_change": { "title": "Whether material drift invalidates the gate (default true, GitHub-style)", "type": "boolean" }, "status": { "enum": [ "requested", "assigned", "notified", "opened", "partially_approved", "approved", "rejected", "changes_requested", "delegated", "expired", "canceled", "superseded" ], "title": "Lifecycle status", "type": "string" } }, "required": [ "id", "gate_key", "status", "approval_strategy", "context_snapshot", "context_hash", "requested_at", "stale_on_context_change", "risk_tier" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.approval_gate:read" ] } ], "summary": "Read Approval gate", "tags": [ "approvals" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.approval_gate/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nDurable approval gate. Carries an `approval_strategy`, eligible principals / role refs, a `context_snapshot` of the facts shown to approvers, and a `context_hash` over the §4.4.2 input set. Material drift on the underlying parameters, prior outputs, or policy invalidates the gate via `workflow_step_context_hash_stable`. Gates can be used standalone for single-action approvals or attached to a workflow step via `approval_gate_for_workflow_step_run`.", "operationId": "get_hospitality_approval_gate_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.approval_gate" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.approval_gate:read" ] } ], "summary": "Read Approval gate as of a watermark", "tags": [ "approvals" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.approval_gate/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nDurable approval gate. Carries an `approval_strategy`, eligible principals / role refs, a `context_snapshot` of the facts shown to approvers, and a `context_hash` over the §4.4.2 input set. Material drift on the underlying parameters, prior outputs, or policy invalidates the gate via `workflow_step_context_hash_stable`. Gates can be used standalone for single-action approvals or attached to a workflow step via `approval_gate_for_workflow_step_run`.", "operationId": "list_links_hospitality_approval_gate", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.approval_gate:read" ] } ], "summary": "List links of Approval gate", "tags": [ "approvals" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.approval_decision_for_gate", "hospitality.link.approval_gate_for_automation", "hospitality.link.approval_gate_for_federated_analysis_definition", "hospitality.link.approval_gate_for_federated_output", "hospitality.link.approval_gate_for_owner_statement", "hospitality.link.approval_gate_for_property_budget", "hospitality.link.approval_gate_for_purpose_grant", "hospitality.link.approval_gate_for_workflow_step_run", "hospitality.link.federated_definition_reviewed_by_gate", "hospitality.link.federated_output_reviewed_by_gate", "hospitality.link.proposed_action_confirmed_via_approval" ] } } ] }, "/v1/object-types/hospitality.approval_gate/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nDurable approval gate. Carries an `approval_strategy`, eligible principals / role refs, a `context_snapshot` of the facts shown to approvers, and a `context_hash` over the §4.4.2 input set. Material drift on the underlying parameters, prior outputs, or policy invalidates the gate via `workflow_step_context_hash_stable`. Gates can be used standalone for single-action approvals or attached to a workflow step via `approval_gate_for_workflow_step_run`.", "operationId": "traverse_hospitality_approval_gate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.approval_decision_for_gate", "hospitality.link.approval_gate_for_automation", "hospitality.link.approval_gate_for_federated_analysis_definition", "hospitality.link.approval_gate_for_federated_output", "hospitality.link.approval_gate_for_owner_statement", "hospitality.link.approval_gate_for_property_budget", "hospitality.link.approval_gate_for_purpose_grant", "hospitality.link.approval_gate_for_workflow_step_run", "hospitality.link.federated_definition_reviewed_by_gate", "hospitality.link.federated_output_reviewed_by_gate", "hospitality.link.proposed_action_confirmed_via_approval" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.approval_gate:read" ] } ], "summary": "Traverse from Approval gate", "tags": [ "approvals" ] } }, "/v1/object-types/hospitality.approval_gate/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nDurable approval gate. Carries an `approval_strategy`, eligible principals / role refs, a `context_snapshot` of the facts shown to approvers, and a `context_hash` over the §4.4.2 input set. Material drift on the underlying parameters, prior outputs, or policy invalidates the gate via `workflow_step_context_hash_stable`. Gates can be used standalone for single-action approvals or attached to a workflow step via `approval_gate_for_workflow_step_run`.", "operationId": "search_hospitality_approval_gate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "gate_key" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "gate_key" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "gate_key" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "gate_key" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "requested", "assigned", "notified", "opened", "partially_approved", "approved", "rejected", "changes_requested", "delegated", "expired", "canceled", "superseded" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approval_strategy" }, "type": { "const": "eq" }, "value": { "enum": [ "any_one", "all", "quorum", "role_based", "ordered_chain", "separation_of_duties" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "required_approval_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "required_approval_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "required_approval_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "eligible_principal_ids" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "eligible_role_refs" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "excluded_principal_ids" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "assigned_to" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "context_snapshot" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "context_hash" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "context_hash" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "context_hash" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "context_hash" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decision_summary" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decision_summary" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notified_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notified_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notified_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notification_target" }, "type": { "const": "eq" }, "value": { "enum": [ "in_product", "slack", "linear", "email", "pms_task", "webhook", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "stale_on_context_change" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "risk_tier" }, "type": { "const": "eq" }, "value": { "enum": [ "read_only", "internal_write", "guest_message", "money_movement", "identity_or_fraud", "clinical_or_regulated", "other_high_risk" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "gate_key", "status", "approval_strategy", "required_approval_count", "requested_by", "context_hash", "decision_summary", "requested_at", "notified_at", "opened_at", "decided_at", "expires_at", "notification_target", "external_reference", "risk_tier" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.approval_gate" }, "properties": { "additionalProperties": false, "properties": { "approval_strategy": { "enum": [ "any_one", "all", "quorum", "role_based", "ordered_chain", "separation_of_duties" ], "title": "How the gate combines decisions to reach `approved`", "type": "string" }, "assigned_to": { "items": { "type": "string" }, "title": "Current assignees, if narrowed", "type": "array" }, "context_hash": { "title": "Canonical JCS+SHA-256 over the §4.4.2 input set", "type": "string" }, "context_snapshot": { "title": "Frozen, redacted facts shown to approvers" }, "decided_at": { "format": "date-time", "title": "Final decision time", "type": "string" }, "decision_summary": { "title": "Final bounded summary", "type": "string" }, "eligible_principal_ids": { "items": { "type": "string" }, "title": "Exact eligible principals when known (Principal::stable_id() shape)", "type": "array" }, "eligible_role_refs": { "items": { "type": "string" }, "title": "Staff roles / groups that may approve", "type": "array" }, "excluded_principal_ids": { "items": { "type": "string" }, "title": "Requesting agent / author / conflicted principals", "type": "array" }, "expires_at": { "format": "date-time", "title": "Gate timeout", "type": "string" }, "external_reference": { "title": "Slack ts, Linear issue id, PMS task id, email thread id, etc.", "type": "string" }, "gate_key": { "title": "Stable within the workflow run or action correlation id", "type": "string" }, "id": { "title": "Gate id", "type": "string" }, "notification_target": { "enum": [ "in_product", "slack", "linear", "email", "pms_task", "webhook", "other" ], "title": "Where the gate notification surfaced", "type": "string" }, "notified_at": { "format": "date-time", "title": "First notification sent", "type": "string" }, "opened_at": { "format": "date-time", "title": "First in-product open/view event when known", "type": "string" }, "requested_at": { "format": "date-time", "title": "Gate creation", "type": "string" }, "requested_by": { "title": "Principal stable id of the gate requester", "type": "string" }, "required_approval_count": { "title": "Required for `approval_strategy = quorum`", "type": "integer" }, "risk_tier": { "enum": [ "read_only", "internal_write", "guest_message", "money_movement", "identity_or_fraud", "clinical_or_regulated", "other_high_risk" ], "title": "Copied from guarded step / action; drives high-risk policy validators", "type": "string" }, "stale_on_context_change": { "title": "Whether material drift invalidates the gate (default true, GitHub-style)", "type": "boolean" }, "status": { "enum": [ "requested", "assigned", "notified", "opened", "partially_approved", "approved", "rejected", "changes_requested", "delegated", "expired", "canceled", "superseded" ], "title": "Lifecycle status", "type": "string" } }, "required": [ "id", "gate_key", "status", "approval_strategy", "context_snapshot", "context_hash", "requested_at", "stale_on_context_change", "risk_tier" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.approval_gate:read" ] } ], "summary": "Search Approval gate", "tags": [ "approvals" ] } }, "/v1/object-types/hospitality.asset/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA piece of equipment a house maintains — the boiler, a room's air conditioner, the kitchen's walk-in (hubOS's hardware). Keyed by `code`, the house's tag for it, unique within the house: `register_asset` with a code the house already holds re-states that asset in place. Stands in at most one place — a room (`asset_in_room`) or a venue (`asset_at_venue`) — or nowhere in particular. Work orders (`work_order_for_asset`) and preventive plans (`maintenance_plan_for_asset`) attach to it as well as to a room, so its service history is a read. `active`, `out_of_service` (with the reason) or `retired` (terminal; its plans retire with it). Manuals and photos hang off it as attachments.", "operationId": "get_hospitality_asset", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.asset" }, "properties": { "additionalProperties": false, "properties": { "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "The trade that maintains it — the work-order categories", "type": "string" }, "code": { "title": "The house's tag for the asset — unique within the house", "type": "string" }, "description": { "title": "Notes on the asset", "type": "string" }, "installed_year": { "title": "Year of installation", "type": "integer" }, "make": { "title": "Manufacturer", "type": "string" }, "model": { "title": "Model", "type": "string" }, "name": { "title": "What the asset is, in words (\"Boiler 2\", \"AC unit, room 101\")", "type": "string" }, "out_of_service_reason": { "title": "Why the asset is out of service (present exactly while it is)", "type": "string" }, "registered_at": { "format": "date-time", "title": "When the asset was first registered", "type": "string" }, "retire_reason": { "title": "Why the asset was retired — removed, replaced, scrapped", "type": "string" }, "retired_at": { "format": "date-time", "title": "When the asset was retired", "type": "string" }, "serial": { "title": "Manufacturer's serial number", "type": "string" }, "status": { "enum": [ "active", "out_of_service", "retired" ], "title": "active, out_of_service (with the reason), or retired", "type": "string" }, "status_changed_at": { "format": "date-time", "title": "When the status last changed", "type": "string" } }, "required": [ "code", "name", "category", "status", "registered_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.asset:read" ] } ], "summary": "Read Asset", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.asset/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA piece of equipment a house maintains — the boiler, a room's air conditioner, the kitchen's walk-in (hubOS's hardware). Keyed by `code`, the house's tag for it, unique within the house: `register_asset` with a code the house already holds re-states that asset in place. Stands in at most one place — a room (`asset_in_room`) or a venue (`asset_at_venue`) — or nowhere in particular. Work orders (`work_order_for_asset`) and preventive plans (`maintenance_plan_for_asset`) attach to it as well as to a room, so its service history is a read. `active`, `out_of_service` (with the reason) or `retired` (terminal; its plans retire with it). Manuals and photos hang off it as attachments.", "operationId": "get_hospitality_asset_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.asset" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.asset:read" ] } ], "summary": "Read Asset as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.asset/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA piece of equipment a house maintains — the boiler, a room's air conditioner, the kitchen's walk-in (hubOS's hardware). Keyed by `code`, the house's tag for it, unique within the house: `register_asset` with a code the house already holds re-states that asset in place. Stands in at most one place — a room (`asset_in_room`) or a venue (`asset_at_venue`) — or nowhere in particular. Work orders (`work_order_for_asset`) and preventive plans (`maintenance_plan_for_asset`) attach to it as well as to a room, so its service history is a read. `active`, `out_of_service` (with the reason) or `retired` (terminal; its plans retire with it). Manuals and photos hang off it as attachments.", "operationId": "list_links_hospitality_asset", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.asset:read" ] } ], "summary": "List links of Asset", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.asset_at_venue", "hospitality.link.asset_in_room", "hospitality.link.checkpoint_result_for_asset", "hospitality.link.maintenance_plan_for_asset", "hospitality.link.stored_object_for_asset", "hospitality.link.work_order_for_asset" ] } } ] }, "/v1/object-types/hospitality.asset/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA piece of equipment a house maintains — the boiler, a room's air conditioner, the kitchen's walk-in (hubOS's hardware). Keyed by `code`, the house's tag for it, unique within the house: `register_asset` with a code the house already holds re-states that asset in place. Stands in at most one place — a room (`asset_in_room`) or a venue (`asset_at_venue`) — or nowhere in particular. Work orders (`work_order_for_asset`) and preventive plans (`maintenance_plan_for_asset`) attach to it as well as to a room, so its service history is a read. `active`, `out_of_service` (with the reason) or `retired` (terminal; its plans retire with it). Manuals and photos hang off it as attachments.", "operationId": "traverse_hospitality_asset", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.asset_at_venue", "hospitality.link.asset_in_room", "hospitality.link.checkpoint_result_for_asset", "hospitality.link.maintenance_plan_for_asset", "hospitality.link.stored_object_for_asset", "hospitality.link.work_order_for_asset" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.asset:read" ] } ], "summary": "Traverse from Asset", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.asset/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA piece of equipment a house maintains — the boiler, a room's air conditioner, the kitchen's walk-in (hubOS's hardware). Keyed by `code`, the house's tag for it, unique within the house: `register_asset` with a code the house already holds re-states that asset in place. Stands in at most one place — a room (`asset_in_room`) or a venue (`asset_at_venue`) — or nowhere in particular. Work orders (`work_order_for_asset`) and preventive plans (`maintenance_plan_for_asset`) attach to it as well as to a room, so its service history is a read. `active`, `out_of_service` (with the reason) or `retired` (terminal; its plans retire with it). Manuals and photos hang off it as attachments.", "operationId": "search_hospitality_asset", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "category" }, "type": { "const": "eq" }, "value": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "make" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "make" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "make" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "make" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "serial" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "serial" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "serial" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "serial" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "installed_year" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "installed_year" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "installed_year" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "out_of_service", "retired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "registered_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "registered_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "registered_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "out_of_service_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "out_of_service_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status_changed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status_changed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status_changed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retire_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retire_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "category", "make", "model", "serial", "installed_year", "description", "status", "registered_at", "out_of_service_reason", "status_changed_at", "retired_at", "retire_reason" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.asset" }, "properties": { "additionalProperties": false, "properties": { "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "The trade that maintains it — the work-order categories", "type": "string" }, "code": { "title": "The house's tag for the asset — unique within the house", "type": "string" }, "description": { "title": "Notes on the asset", "type": "string" }, "installed_year": { "title": "Year of installation", "type": "integer" }, "make": { "title": "Manufacturer", "type": "string" }, "model": { "title": "Model", "type": "string" }, "name": { "title": "What the asset is, in words (\"Boiler 2\", \"AC unit, room 101\")", "type": "string" }, "out_of_service_reason": { "title": "Why the asset is out of service (present exactly while it is)", "type": "string" }, "registered_at": { "format": "date-time", "title": "When the asset was first registered", "type": "string" }, "retire_reason": { "title": "Why the asset was retired — removed, replaced, scrapped", "type": "string" }, "retired_at": { "format": "date-time", "title": "When the asset was retired", "type": "string" }, "serial": { "title": "Manufacturer's serial number", "type": "string" }, "status": { "enum": [ "active", "out_of_service", "retired" ], "title": "active, out_of_service (with the reason), or retired", "type": "string" }, "status_changed_at": { "format": "date-time", "title": "When the status last changed", "type": "string" } }, "required": [ "code", "name", "category", "status", "registered_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.asset:read" ] } ], "summary": "Search Asset", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.automation/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA declarative monitor→effect rule: when a condition is met — an object entering/leaving/changing within a filtered object set, a periodic sweep, or a cron schedule — the automation fires an effect (apply a registered action, call a read-only function, or send a notification). The effect never mutates state directly; `apply_action` fires the target action through the normal scope-checked action surface, and the `requires_approval` variant routes it through a 0020 approval_gate instead of applying. Only `active` automations fire. Mirrors Palantir AIP Automate; see `products/labs/docs/palantir-aip-deep-scan.md` §4.1.", "operationId": "get_hospitality_automation", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.automation" }, "properties": { "additionalProperties": false, "properties": { "approval_policy_ref": { "title": "The approval policy the staged gate is opened under (proposal 0020)", "type": "string" }, "condition_kind": { "enum": [ "object_set_added", "object_set_removed", "object_set_modified", "object_set_all", "time_cron", "event_named" ], "title": "The trigger-predicate class", "type": "string" }, "created_by": { "title": "Principal::stable_id() of the operator/agent that defined it — the audit anchor", "type": "string" }, "cron_expression": { "title": "The schedule (5-field cron, evaluated in UTC by the host-side schedule worker): required for `time_cron` and for the `object_set_all` sweep (`automation_condition_coherent`); meaningless for the tail-driven kinds", "type": "string" }, "description_text": { "title": "What this automation is for — the operator's own note", "type": "string" }, "display_name": { "title": "Human-readable name, surfaced in the operator console", "type": "string" }, "effect_action": { "title": "For `apply_action`: the registered action to fire (ApiName form); validated against the registry and forbidden from targeting an internal-only action (`automation_effect_coherent`, `automation_no_internal_effect_action`)", "type": "string" }, "effect_function": { "title": "For `call_function`: the read-only registry function to invoke (ApiName form)", "type": "string" }, "effect_kind": { "enum": [ "apply_action", "call_function", "send_notification" ], "title": "The effect fired when the condition is met", "type": "string" }, "effect_notification_template": { "title": "For `send_notification`: the templated notification body/target (JSON)" }, "effect_params_template": { "title": "Template mapping triggering-object fields → the effect's input params (JSON; `${object.}` / `${previous.}` placeholders resolved per-firing by the evaluator)" }, "event_type_ref": { "title": "For `event_named`: the named domain event the condition watches (ApiName form, e.g. `room_queue.room_ready`). The event's payload is the image `object_set_filter` matches and `${event.}` reads; required for `event_named` and forbidden for every other kind (`automation_condition_coherent`)", "type": "string" }, "execution_mode": { "enum": [ "per_object", "batch" ], "title": "Per-object vs batch effect firing for object-set conditions", "type": "string" }, "id": { "title": "Automation id", "type": "string" }, "max_cascade_depth": { "title": "Loop guard: the maximum trigger-chain depth an effect firing may reach before the evaluator suppresses it (default 3). An automation whose effect trips another automation increments the depth along the `correlation_id` lineage", "type": "integer" }, "modified_property_watch": { "title": "For `object_set_modified`: the property api-names whose change trips the condition (JSON array); empty/absent = any property change. An entry `name:decreased` / `name:increased` trips only when that number moved that way (an absent side reads as zero)" }, "object_set_filter": { "title": "The search-filter predicate that defines the watched object set over `object_type_ref` (same filter grammar as object search); absent = every object of the type" }, "object_type_ref": { "title": "The object type the object-set condition watches (ApiName form); required for `object_set_*` kinds, absent for `time_cron` (`automation_condition_coherent`)", "type": "string" }, "requires_approval": { "title": "When true, the effect opens a 0020 approval_gate instead of applying (the human-approval-staging variant); requires `approval_policy_ref` (`automation_approval_requires_policy`)", "type": "boolean" }, "status": { "enum": [ "draft", "active", "paused", "archived" ], "title": "Enablement lifecycle; only `active` automations fire", "type": "string" } }, "required": [ "id", "display_name", "created_by", "condition_kind", "effect_kind", "execution_mode", "requires_approval", "max_cascade_depth", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.automation:read" ] } ], "summary": "Read Automation", "tags": [ "automation" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.automation/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA declarative monitor→effect rule: when a condition is met — an object entering/leaving/changing within a filtered object set, a periodic sweep, or a cron schedule — the automation fires an effect (apply a registered action, call a read-only function, or send a notification). The effect never mutates state directly; `apply_action` fires the target action through the normal scope-checked action surface, and the `requires_approval` variant routes it through a 0020 approval_gate instead of applying. Only `active` automations fire. Mirrors Palantir AIP Automate; see `products/labs/docs/palantir-aip-deep-scan.md` §4.1.", "operationId": "get_hospitality_automation_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.automation" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.automation:read" ] } ], "summary": "Read Automation as of a watermark", "tags": [ "automation" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.automation/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA declarative monitor→effect rule: when a condition is met — an object entering/leaving/changing within a filtered object set, a periodic sweep, or a cron schedule — the automation fires an effect (apply a registered action, call a read-only function, or send a notification). The effect never mutates state directly; `apply_action` fires the target action through the normal scope-checked action surface, and the `requires_approval` variant routes it through a 0020 approval_gate instead of applying. Only `active` automations fire. Mirrors Palantir AIP Automate; see `products/labs/docs/palantir-aip-deep-scan.md` §4.1.", "operationId": "list_links_hospitality_automation", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.automation:read" ] } ], "summary": "List links of Automation", "tags": [ "automation" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.approval_gate_for_automation" ] } } ] }, "/v1/object-types/hospitality.automation/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA declarative monitor→effect rule: when a condition is met — an object entering/leaving/changing within a filtered object set, a periodic sweep, or a cron schedule — the automation fires an effect (apply a registered action, call a read-only function, or send a notification). The effect never mutates state directly; `apply_action` fires the target action through the normal scope-checked action surface, and the `requires_approval` variant routes it through a 0020 approval_gate instead of applying. Only `active` automations fire. Mirrors Palantir AIP Automate; see `products/labs/docs/palantir-aip-deep-scan.md` §4.1.", "operationId": "traverse_hospitality_automation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.approval_gate_for_automation" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.automation:read" ] } ], "summary": "Traverse from Automation", "tags": [ "automation" ] } }, "/v1/object-types/hospitality.automation/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA declarative monitor→effect rule: when a condition is met — an object entering/leaving/changing within a filtered object set, a periodic sweep, or a cron schedule — the automation fires an effect (apply a registered action, call a read-only function, or send a notification). The effect never mutates state directly; `apply_action` fires the target action through the normal scope-checked action surface, and the `requires_approval` variant routes it through a 0020 approval_gate instead of applying. Only `active` automations fire. Mirrors Palantir AIP Automate; see `products/labs/docs/palantir-aip-deep-scan.md` §4.1.", "operationId": "search_hospitality_automation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "created_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "created_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "created_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "created_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "condition_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "object_set_added", "object_set_removed", "object_set_modified", "object_set_all", "time_cron", "event_named" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "object_type_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "object_type_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "object_type_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "object_type_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "object_set_filter" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "modified_property_watch" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cron_expression" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cron_expression" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cron_expression" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cron_expression" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "event_type_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "event_type_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "event_type_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "event_type_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effect_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "apply_action", "call_function", "send_notification" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effect_action" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effect_action" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effect_action" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effect_action" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effect_function" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effect_function" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effect_function" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effect_function" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effect_params_template" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effect_notification_template" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "execution_mode" }, "type": { "const": "eq" }, "value": { "enum": [ "per_object", "batch" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requires_approval" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approval_policy_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approval_policy_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approval_policy_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approval_policy_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_cascade_depth" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_cascade_depth" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_cascade_depth" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "draft", "active", "paused", "archived" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "display_name", "description_text", "created_by", "condition_kind", "object_type_ref", "cron_expression", "event_type_ref", "effect_kind", "effect_action", "effect_function", "execution_mode", "approval_policy_ref", "max_cascade_depth", "status" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.automation" }, "properties": { "additionalProperties": false, "properties": { "approval_policy_ref": { "title": "The approval policy the staged gate is opened under (proposal 0020)", "type": "string" }, "condition_kind": { "enum": [ "object_set_added", "object_set_removed", "object_set_modified", "object_set_all", "time_cron", "event_named" ], "title": "The trigger-predicate class", "type": "string" }, "created_by": { "title": "Principal::stable_id() of the operator/agent that defined it — the audit anchor", "type": "string" }, "cron_expression": { "title": "The schedule (5-field cron, evaluated in UTC by the host-side schedule worker): required for `time_cron` and for the `object_set_all` sweep (`automation_condition_coherent`); meaningless for the tail-driven kinds", "type": "string" }, "description_text": { "title": "What this automation is for — the operator's own note", "type": "string" }, "display_name": { "title": "Human-readable name, surfaced in the operator console", "type": "string" }, "effect_action": { "title": "For `apply_action`: the registered action to fire (ApiName form); validated against the registry and forbidden from targeting an internal-only action (`automation_effect_coherent`, `automation_no_internal_effect_action`)", "type": "string" }, "effect_function": { "title": "For `call_function`: the read-only registry function to invoke (ApiName form)", "type": "string" }, "effect_kind": { "enum": [ "apply_action", "call_function", "send_notification" ], "title": "The effect fired when the condition is met", "type": "string" }, "effect_notification_template": { "title": "For `send_notification`: the templated notification body/target (JSON)" }, "effect_params_template": { "title": "Template mapping triggering-object fields → the effect's input params (JSON; `${object.}` / `${previous.}` placeholders resolved per-firing by the evaluator)" }, "event_type_ref": { "title": "For `event_named`: the named domain event the condition watches (ApiName form, e.g. `room_queue.room_ready`). The event's payload is the image `object_set_filter` matches and `${event.}` reads; required for `event_named` and forbidden for every other kind (`automation_condition_coherent`)", "type": "string" }, "execution_mode": { "enum": [ "per_object", "batch" ], "title": "Per-object vs batch effect firing for object-set conditions", "type": "string" }, "id": { "title": "Automation id", "type": "string" }, "max_cascade_depth": { "title": "Loop guard: the maximum trigger-chain depth an effect firing may reach before the evaluator suppresses it (default 3). An automation whose effect trips another automation increments the depth along the `correlation_id` lineage", "type": "integer" }, "modified_property_watch": { "title": "For `object_set_modified`: the property api-names whose change trips the condition (JSON array); empty/absent = any property change. An entry `name:decreased` / `name:increased` trips only when that number moved that way (an absent side reads as zero)" }, "object_set_filter": { "title": "The search-filter predicate that defines the watched object set over `object_type_ref` (same filter grammar as object search); absent = every object of the type" }, "object_type_ref": { "title": "The object type the object-set condition watches (ApiName form); required for `object_set_*` kinds, absent for `time_cron` (`automation_condition_coherent`)", "type": "string" }, "requires_approval": { "title": "When true, the effect opens a 0020 approval_gate instead of applying (the human-approval-staging variant); requires `approval_policy_ref` (`automation_approval_requires_policy`)", "type": "boolean" }, "status": { "enum": [ "draft", "active", "paused", "archived" ], "title": "Enablement lifecycle; only `active` automations fire", "type": "string" } }, "required": [ "id", "display_name", "created_by", "condition_kind", "effect_kind", "execution_mode", "requires_approval", "max_cascade_depth", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.automation:read" ] } ], "summary": "Search Automation", "tags": [ "automation" ] } }, "/v1/object-types/hospitality.automation_run/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA frozen, auditable record of one automation firing: which objects tripped the condition (with their current + previous image), which effect fired, and the terminal outcome (`effect_applied`, `staged_for_approval`, `effect_failed`, or `suppressed`). Written by the host-side evaluator via the internal `record_automation_run` action; immutable post-insert like every other Aerandil audit artefact. The `effect_correlation_id` joins to the chained action's event stream; `approval_gate_ref` joins to the staged gate.", "operationId": "get_hospitality_automation_run", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.automation_run" }, "properties": { "additionalProperties": false, "properties": { "approval_gate_ref": { "title": "For `staged_for_approval`: the opened 0020 approval_gate id (`automation_run_outcome_coherent`)", "type": "string" }, "automation_ref": { "title": "The automation that fired (id of the `automation` object)", "type": "string" }, "cascade_depth": { "title": "This firing's depth in the trigger chain (0 = directly operator/data-driven)", "type": "integer" }, "condition_kind": { "enum": [ "object_set_added", "object_set_removed", "object_set_modified", "object_set_all", "time_cron", "event_named" ], "title": "Snapshot of the automation's condition kind at firing time", "type": "string" }, "correlation_id": { "title": "Trigger-lineage anchor — shared across a cascade so depth and cycles are traceable", "type": "string" }, "effect_correlation_id": { "title": "For `effect_applied` on `apply_action`: the chained action's correlation id — the audit-trail join (`automation_run_outcome_coherent`)", "type": "string" }, "effect_input_snapshot": { "title": "The resolved effect input the evaluator dispatched — the audit-grade record of what actually fired" }, "effect_kind": { "enum": [ "apply_action", "call_function", "send_notification" ], "title": "Snapshot of the effect kind fired", "type": "string" }, "effect_target": { "title": "The action/function fired (ApiName form; absent for `send_notification`)", "type": "string" }, "error_text": { "title": "For `effect_failed`: the error the effect returned (`automation_run_outcome_coherent`)", "type": "string" }, "fired_at": { "format": "date-time", "title": "When the evaluator dispatched the effect", "type": "string" }, "id": { "title": "Automation run id", "type": "string" }, "outcome": { "enum": [ "effect_applied", "staged_for_approval", "effect_failed", "suppressed" ], "title": "Terminal outcome of the firing", "type": "string" }, "recorded_correlation_id": { "title": "The correlation id this run was itself recorded under — stamped by `record_automation_run` from its own invocation, so every event the recording emits joins back to the run and the cascade guard sees the lane's own bookkeeping as an echo, never a fresh depth-0 trigger", "type": "string" }, "triggering_delta_snapshot": { "title": "For `object_set_modified`: the before/after delta the evaluator matched; bounded excerpts only" }, "triggering_object_refs": { "title": "Ids of the objects that tripped the condition (JSON array; bounded); for `event_named`, the triggering event's sequence number" }, "triggering_object_type": { "title": "The watched object type (absent for `time_cron`); for `event_named`, the named event type that tripped it", "type": "string" } }, "required": [ "id", "automation_ref", "fired_at", "condition_kind", "effect_kind", "outcome", "cascade_depth", "correlation_id" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.automation_run:read" ] } ], "summary": "Read Automation run", "tags": [ "automation" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.automation_run/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA frozen, auditable record of one automation firing: which objects tripped the condition (with their current + previous image), which effect fired, and the terminal outcome (`effect_applied`, `staged_for_approval`, `effect_failed`, or `suppressed`). Written by the host-side evaluator via the internal `record_automation_run` action; immutable post-insert like every other Aerandil audit artefact. The `effect_correlation_id` joins to the chained action's event stream; `approval_gate_ref` joins to the staged gate.", "operationId": "get_hospitality_automation_run_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.automation_run" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.automation_run:read" ] } ], "summary": "Read Automation run as of a watermark", "tags": [ "automation" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.automation_run/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA frozen, auditable record of one automation firing: which objects tripped the condition (with their current + previous image), which effect fired, and the terminal outcome (`effect_applied`, `staged_for_approval`, `effect_failed`, or `suppressed`). Written by the host-side evaluator via the internal `record_automation_run` action; immutable post-insert like every other Aerandil audit artefact. The `effect_correlation_id` joins to the chained action's event stream; `approval_gate_ref` joins to the staged gate.", "operationId": "search_hospitality_automation_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "automation_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "automation_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "automation_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "automation_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fired_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fired_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fired_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "condition_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "object_set_added", "object_set_removed", "object_set_modified", "object_set_all", "time_cron", "event_named" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "triggering_object_type" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "triggering_object_type" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "triggering_object_type" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "triggering_object_type" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "triggering_object_refs" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "triggering_delta_snapshot" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effect_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "apply_action", "call_function", "send_notification" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effect_target" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effect_target" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effect_target" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effect_target" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effect_input_snapshot" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "outcome" }, "type": { "const": "eq" }, "value": { "enum": [ "effect_applied", "staged_for_approval", "effect_failed", "suppressed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effect_correlation_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effect_correlation_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effect_correlation_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effect_correlation_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_correlation_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_correlation_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_correlation_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_correlation_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approval_gate_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approval_gate_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approval_gate_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approval_gate_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "error_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "error_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cascade_depth" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cascade_depth" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cascade_depth" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "correlation_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "correlation_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "correlation_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "correlation_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "automation_ref", "fired_at", "condition_kind", "triggering_object_type", "effect_kind", "effect_target", "outcome", "effect_correlation_id", "recorded_correlation_id", "approval_gate_ref", "error_text", "cascade_depth", "correlation_id" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.automation_run" }, "properties": { "additionalProperties": false, "properties": { "approval_gate_ref": { "title": "For `staged_for_approval`: the opened 0020 approval_gate id (`automation_run_outcome_coherent`)", "type": "string" }, "automation_ref": { "title": "The automation that fired (id of the `automation` object)", "type": "string" }, "cascade_depth": { "title": "This firing's depth in the trigger chain (0 = directly operator/data-driven)", "type": "integer" }, "condition_kind": { "enum": [ "object_set_added", "object_set_removed", "object_set_modified", "object_set_all", "time_cron", "event_named" ], "title": "Snapshot of the automation's condition kind at firing time", "type": "string" }, "correlation_id": { "title": "Trigger-lineage anchor — shared across a cascade so depth and cycles are traceable", "type": "string" }, "effect_correlation_id": { "title": "For `effect_applied` on `apply_action`: the chained action's correlation id — the audit-trail join (`automation_run_outcome_coherent`)", "type": "string" }, "effect_input_snapshot": { "title": "The resolved effect input the evaluator dispatched — the audit-grade record of what actually fired" }, "effect_kind": { "enum": [ "apply_action", "call_function", "send_notification" ], "title": "Snapshot of the effect kind fired", "type": "string" }, "effect_target": { "title": "The action/function fired (ApiName form; absent for `send_notification`)", "type": "string" }, "error_text": { "title": "For `effect_failed`: the error the effect returned (`automation_run_outcome_coherent`)", "type": "string" }, "fired_at": { "format": "date-time", "title": "When the evaluator dispatched the effect", "type": "string" }, "id": { "title": "Automation run id", "type": "string" }, "outcome": { "enum": [ "effect_applied", "staged_for_approval", "effect_failed", "suppressed" ], "title": "Terminal outcome of the firing", "type": "string" }, "recorded_correlation_id": { "title": "The correlation id this run was itself recorded under — stamped by `record_automation_run` from its own invocation, so every event the recording emits joins back to the run and the cascade guard sees the lane's own bookkeeping as an echo, never a fresh depth-0 trigger", "type": "string" }, "triggering_delta_snapshot": { "title": "For `object_set_modified`: the before/after delta the evaluator matched; bounded excerpts only" }, "triggering_object_refs": { "title": "Ids of the objects that tripped the condition (JSON array; bounded); for `event_named`, the triggering event's sequence number" }, "triggering_object_type": { "title": "The watched object type (absent for `time_cron`); for `event_named`, the named event type that tripped it", "type": "string" } }, "required": [ "id", "automation_ref", "fired_at", "condition_kind", "effect_kind", "outcome", "cascade_depth", "correlation_id" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.automation_run:read" ] } ], "summary": "Search Automation run", "tags": [ "automation" ] } }, "/v1/object-types/hospitality.availability_day/objects/{id}": { "get": { "description": "Read an existing instance.\n\nInventory ledger entry per `(property, room_type, business_date)`. The single source of truth for whether a room is sellable. `physical` is the underlying room count; `sellable` is the count exposed to channels after holds/walls; `sold` is occupancy as of the snapshot; `oversell_limit` is the operator's declared headroom above `sellable`, which offsets cancellations and no-shows — declared by `set_availability`, moved by an applied sell-limit recommendation; `declared_oversell_limit` keeps the operator's declaration (what a recommendation's reset restores) and `oversell_ceiling` the most headroom a recommendation may set; `out_of_order` is the count of this type's rooms blocked out of order this date (owned by the room_status_block verbs, never by set_availability); `blocked` is the count held by group blocks and not yet picked up (owned by the group-block verbs, likewise never by set_availability). The booking flow refuses at `sellable - out_of_order - blocked + oversell_limit`, and the validator on this type enforces `0 <= sold <= sellable + oversell_limit`, `sellable <= physical`, `0 <= out_of_order <= physical`, and `0 <= blocked <= physical` on every write.", "operationId": "get_hospitality_availability_day", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.availability_day" }, "properties": { "additionalProperties": false, "properties": { "blocked": { "title": "Rooms held by group blocks and not yet picked up", "type": "integer" }, "business_date": { "format": "date", "title": "Business date", "type": "string" }, "committed_oversell": { "title": "Room-nights accepted past the ceiling because a channel had already sold them", "type": "integer" }, "declared_oversell_limit": { "description": "The oversell headroom the operator declared — what a sell-limit recommendation's reset restores", "title": "Declared oversell limit", "type": "integer" }, "id": { "title": "Availability id", "type": "string" }, "notes": { "title": "Notes", "type": "string" }, "out_of_order": { "title": "Rooms of this type blocked out of order this date", "type": "integer" }, "oversell_ceiling": { "description": "The most oversell headroom a sell-limit recommendation may set (the operator's guardrail; absent, the declared limit)", "title": "Oversell ceiling", "type": "integer" }, "oversell_limit": { "title": "Oversell limit", "type": "integer" }, "physical": { "title": "Physical room count", "type": "integer" }, "sellable": { "title": "Sellable room count", "type": "integer" }, "sold": { "title": "Sold count", "type": "integer" } }, "required": [ "id", "business_date", "physical", "sellable", "sold" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.availability_day:read" ] } ], "summary": "Read Availability day", "tags": [ "distribution" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.availability_day/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nInventory ledger entry per `(property, room_type, business_date)`. The single source of truth for whether a room is sellable. `physical` is the underlying room count; `sellable` is the count exposed to channels after holds/walls; `sold` is occupancy as of the snapshot; `oversell_limit` is the operator's declared headroom above `sellable`, which offsets cancellations and no-shows — declared by `set_availability`, moved by an applied sell-limit recommendation; `declared_oversell_limit` keeps the operator's declaration (what a recommendation's reset restores) and `oversell_ceiling` the most headroom a recommendation may set; `out_of_order` is the count of this type's rooms blocked out of order this date (owned by the room_status_block verbs, never by set_availability); `blocked` is the count held by group blocks and not yet picked up (owned by the group-block verbs, likewise never by set_availability). The booking flow refuses at `sellable - out_of_order - blocked + oversell_limit`, and the validator on this type enforces `0 <= sold <= sellable + oversell_limit`, `sellable <= physical`, `0 <= out_of_order <= physical`, and `0 <= blocked <= physical` on every write.", "operationId": "get_hospitality_availability_day_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.availability_day" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.availability_day:read" ] } ], "summary": "Read Availability day as of a watermark", "tags": [ "distribution" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.availability_day/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nInventory ledger entry per `(property, room_type, business_date)`. The single source of truth for whether a room is sellable. `physical` is the underlying room count; `sellable` is the count exposed to channels after holds/walls; `sold` is occupancy as of the snapshot; `oversell_limit` is the operator's declared headroom above `sellable`, which offsets cancellations and no-shows — declared by `set_availability`, moved by an applied sell-limit recommendation; `declared_oversell_limit` keeps the operator's declaration (what a recommendation's reset restores) and `oversell_ceiling` the most headroom a recommendation may set; `out_of_order` is the count of this type's rooms blocked out of order this date (owned by the room_status_block verbs, never by set_availability); `blocked` is the count held by group blocks and not yet picked up (owned by the group-block verbs, likewise never by set_availability). The booking flow refuses at `sellable - out_of_order - blocked + oversell_limit`, and the validator on this type enforces `0 <= sold <= sellable + oversell_limit`, `sellable <= physical`, `0 <= out_of_order <= physical`, and `0 <= blocked <= physical` on every write.", "operationId": "list_links_hospitality_availability_day", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.availability_day:read" ] } ], "summary": "List links of Availability day", "tags": [ "distribution" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.property_has_availability_day", "hospitality.link.room_type_has_availability_day", "hospitality.link.sell_limit_recommendation_applied_to_availability_day" ] } } ] }, "/v1/object-types/hospitality.availability_day/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nInventory ledger entry per `(property, room_type, business_date)`. The single source of truth for whether a room is sellable. `physical` is the underlying room count; `sellable` is the count exposed to channels after holds/walls; `sold` is occupancy as of the snapshot; `oversell_limit` is the operator's declared headroom above `sellable`, which offsets cancellations and no-shows — declared by `set_availability`, moved by an applied sell-limit recommendation; `declared_oversell_limit` keeps the operator's declaration (what a recommendation's reset restores) and `oversell_ceiling` the most headroom a recommendation may set; `out_of_order` is the count of this type's rooms blocked out of order this date (owned by the room_status_block verbs, never by set_availability); `blocked` is the count held by group blocks and not yet picked up (owned by the group-block verbs, likewise never by set_availability). The booking flow refuses at `sellable - out_of_order - blocked + oversell_limit`, and the validator on this type enforces `0 <= sold <= sellable + oversell_limit`, `sellable <= physical`, `0 <= out_of_order <= physical`, and `0 <= blocked <= physical` on every write.", "operationId": "traverse_hospitality_availability_day", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.property_has_availability_day", "hospitality.link.room_type_has_availability_day", "hospitality.link.sell_limit_recommendation_applied_to_availability_day" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.availability_day:read" ] } ], "summary": "Traverse from Availability day", "tags": [ "distribution" ] } }, "/v1/object-types/hospitality.availability_day/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nInventory ledger entry per `(property, room_type, business_date)`. The single source of truth for whether a room is sellable. `physical` is the underlying room count; `sellable` is the count exposed to channels after holds/walls; `sold` is occupancy as of the snapshot; `oversell_limit` is the operator's declared headroom above `sellable`, which offsets cancellations and no-shows — declared by `set_availability`, moved by an applied sell-limit recommendation; `declared_oversell_limit` keeps the operator's declaration (what a recommendation's reset restores) and `oversell_ceiling` the most headroom a recommendation may set; `out_of_order` is the count of this type's rooms blocked out of order this date (owned by the room_status_block verbs, never by set_availability); `blocked` is the count held by group blocks and not yet picked up (owned by the group-block verbs, likewise never by set_availability). The booking flow refuses at `sellable - out_of_order - blocked + oversell_limit`, and the validator on this type enforces `0 <= sold <= sellable + oversell_limit`, `sellable <= physical`, `0 <= out_of_order <= physical`, and `0 <= blocked <= physical` on every write.", "operationId": "search_hospitality_availability_day", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "physical" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "physical" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "physical" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sellable" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sellable" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sellable" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sold" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sold" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sold" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "blocked" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "blocked" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "blocked" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "oversell_limit" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "oversell_limit" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "oversell_limit" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "declared_oversell_limit" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "declared_oversell_limit" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "declared_oversell_limit" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "oversell_ceiling" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "oversell_ceiling" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "oversell_ceiling" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "out_of_order" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "out_of_order" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "out_of_order" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "committed_oversell" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "committed_oversell" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "committed_oversell" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "business_date", "physical", "sellable", "sold", "blocked", "oversell_limit", "declared_oversell_limit", "oversell_ceiling", "out_of_order", "committed_oversell", "notes" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.availability_day" }, "properties": { "additionalProperties": false, "properties": { "blocked": { "title": "Rooms held by group blocks and not yet picked up", "type": "integer" }, "business_date": { "format": "date", "title": "Business date", "type": "string" }, "committed_oversell": { "title": "Room-nights accepted past the ceiling because a channel had already sold them", "type": "integer" }, "declared_oversell_limit": { "description": "The oversell headroom the operator declared — what a sell-limit recommendation's reset restores", "title": "Declared oversell limit", "type": "integer" }, "id": { "title": "Availability id", "type": "string" }, "notes": { "title": "Notes", "type": "string" }, "out_of_order": { "title": "Rooms of this type blocked out of order this date", "type": "integer" }, "oversell_ceiling": { "description": "The most oversell headroom a sell-limit recommendation may set (the operator's guardrail; absent, the declared limit)", "title": "Oversell ceiling", "type": "integer" }, "oversell_limit": { "title": "Oversell limit", "type": "integer" }, "physical": { "title": "Physical room count", "type": "integer" }, "sellable": { "title": "Sellable room count", "type": "integer" }, "sold": { "title": "Sold count", "type": "integer" } }, "required": [ "id", "business_date", "physical", "sellable", "sold" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.availability_day:read" ] } ], "summary": "Search Availability day", "tags": [ "distribution" ] } }, "/v1/object-types/hospitality.banquet_event_order/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe banquet event order (function sheet) for one function event: the resources the departments set, cook and serve — its lines — with the setup, service and billing notes, issued to the house under a revision number and re-issued when a line changes after distribution. Once the event is actual, `post_banquet_event_charges` posts every line at the billable count to the order's folio or the block's master folio and freezes the order as `posted`.", "operationId": "get_hospitality_banquet_event_order", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_event_order" }, "properties": { "additionalProperties": false, "properties": { "av_notes": { "title": "Audiovisual: equipment, technicians, rehearsal", "type": "string" }, "billing_instructions": { "title": "How the client pays — master account, deposits, what the guests settle", "type": "string" }, "currency": { "format": "iso-4217", "title": "Currency every line is priced in", "type": "string" }, "issued_at": { "format": "date-time", "title": "When the current revision went to the departments", "type": "string" }, "number": { "title": "BEO number", "type": "string" }, "posted_at": { "format": "date-time", "title": "When the charges were posted", "type": "string" }, "revision": { "title": "How many times the order has been issued", "type": "integer" }, "service_charge_rate": { "format": "decimal", "title": "Service charge applied to food and beverage lines at posting (0.125 = 12.5%)", "type": "string" }, "service_notes": { "title": "Service: the run of show, course timings, bar hours", "type": "string" }, "setup_notes": { "title": "Setup: tables, linen, staging, signage", "type": "string" }, "status": { "enum": [ "draft", "issued", "revised", "posted", "cancelled" ], "title": "Order status", "type": "string" } }, "required": [ "number", "status", "revision", "currency" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.banquet_event_order:read" ] } ], "summary": "Read Banquet event order", "tags": [ "catering" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.banquet_event_order/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe banquet event order (function sheet) for one function event: the resources the departments set, cook and serve — its lines — with the setup, service and billing notes, issued to the house under a revision number and re-issued when a line changes after distribution. Once the event is actual, `post_banquet_event_charges` posts every line at the billable count to the order's folio or the block's master folio and freezes the order as `posted`.", "operationId": "get_hospitality_banquet_event_order_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.banquet_event_order" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.banquet_event_order:read" ] } ], "summary": "Read Banquet event order as of a watermark", "tags": [ "catering" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.banquet_event_order/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe banquet event order (function sheet) for one function event: the resources the departments set, cook and serve — its lines — with the setup, service and billing notes, issued to the house under a revision number and re-issued when a line changes after distribution. Once the event is actual, `post_banquet_event_charges` posts every line at the billable count to the order's folio or the block's master folio and freezes the order as `posted`.", "operationId": "list_links_hospitality_banquet_event_order", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.banquet_event_order:read" ] } ], "summary": "List links of Banquet event order", "tags": [ "catering" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.banquet_order_at_outlet", "hospitality.link.banquet_order_has_line", "hospitality.link.banquet_order_posts_to_folio", "hospitality.link.function_event_has_order" ] } } ] }, "/v1/object-types/hospitality.banquet_event_order/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe banquet event order (function sheet) for one function event: the resources the departments set, cook and serve — its lines — with the setup, service and billing notes, issued to the house under a revision number and re-issued when a line changes after distribution. Once the event is actual, `post_banquet_event_charges` posts every line at the billable count to the order's folio or the block's master folio and freezes the order as `posted`.", "operationId": "traverse_hospitality_banquet_event_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.banquet_order_at_outlet", "hospitality.link.banquet_order_has_line", "hospitality.link.banquet_order_posts_to_folio", "hospitality.link.function_event_has_order" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.banquet_event_order:read" ] } ], "summary": "Traverse from Banquet event order", "tags": [ "catering" ] } }, "/v1/object-types/hospitality.banquet_event_order/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe banquet event order (function sheet) for one function event: the resources the departments set, cook and serve — its lines — with the setup, service and billing notes, issued to the house under a revision number and re-issued when a line changes after distribution. Once the event is actual, `post_banquet_event_charges` posts every line at the billable count to the order's folio or the block's master folio and freezes the order as `posted`.", "operationId": "search_hospitality_banquet_event_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "number" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "number" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "number" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "number" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "draft", "issued", "revised", "posted", "cancelled" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revision" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revision" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revision" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "currency" }, "type": { "const": "eq" }, "value": { "format": "iso-4217", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "posted_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "posted_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "posted_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "service_charge_rate" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "service_charge_rate" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "service_charge_rate" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "billing_instructions" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "billing_instructions" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "setup_notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "setup_notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "service_notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "service_notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "av_notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "av_notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "number", "status", "revision", "issued_at", "posted_at", "service_charge_rate", "billing_instructions", "setup_notes", "service_notes", "av_notes" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_event_order" }, "properties": { "additionalProperties": false, "properties": { "av_notes": { "title": "Audiovisual: equipment, technicians, rehearsal", "type": "string" }, "billing_instructions": { "title": "How the client pays — master account, deposits, what the guests settle", "type": "string" }, "currency": { "format": "iso-4217", "title": "Currency every line is priced in", "type": "string" }, "issued_at": { "format": "date-time", "title": "When the current revision went to the departments", "type": "string" }, "number": { "title": "BEO number", "type": "string" }, "posted_at": { "format": "date-time", "title": "When the charges were posted", "type": "string" }, "revision": { "title": "How many times the order has been issued", "type": "integer" }, "service_charge_rate": { "format": "decimal", "title": "Service charge applied to food and beverage lines at posting (0.125 = 12.5%)", "type": "string" }, "service_notes": { "title": "Service: the run of show, course timings, bar hours", "type": "string" }, "setup_notes": { "title": "Setup: tables, linen, staging, signage", "type": "string" }, "status": { "enum": [ "draft", "issued", "revised", "posted", "cancelled" ], "title": "Order status", "type": "string" } }, "required": [ "number", "status", "revision", "currency" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.banquet_event_order:read" ] } ], "summary": "Search Banquet event order", "tags": [ "catering" ] } }, "/v1/object-types/hospitality.banquet_order_line/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne resource on a banquet event order — a menu, a coffee break, the room, a screen. `quantity_basis` says whether it bills per person (times the event's billable count) or as a fixed quantity; `unit_price` is in the order's currency. Posting links the line to the charge it became.", "operationId": "get_hospitality_banquet_order_line", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_order_line" }, "properties": { "additionalProperties": false, "properties": { "category": { "enum": [ "room_rental", "food", "beverage", "audio_visual", "equipment", "labour", "decor", "entertainment", "other" ], "title": "Section of the sheet the line belongs to", "type": "string" }, "description": { "title": "What the line is", "type": "string" }, "id": { "title": "Line id", "type": "string" }, "notes": { "title": "Dietary, presentation, placement", "type": "string" }, "quantity": { "title": "Fixed quantity, or units per person", "type": "integer" }, "quantity_basis": { "enum": [ "per_person", "fixed" ], "title": "Per person, or a fixed quantity", "type": "string" }, "sequence": { "title": "Order of the line on the sheet", "type": "integer" }, "serve_at": { "format": "date-time", "title": "When the line is served or set", "type": "string" }, "unit_price": { "description": "Price per unit", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Banquet order line unit price", "type": "object" } }, "required": [ "id", "sequence", "category", "description", "quantity_basis", "quantity" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.banquet_order_line:read" ] } ], "summary": "Read Banquet order line", "tags": [ "catering" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.banquet_order_line/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne resource on a banquet event order — a menu, a coffee break, the room, a screen. `quantity_basis` says whether it bills per person (times the event's billable count) or as a fixed quantity; `unit_price` is in the order's currency. Posting links the line to the charge it became.", "operationId": "get_hospitality_banquet_order_line_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.banquet_order_line" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.banquet_order_line:read" ] } ], "summary": "Read Banquet order line as of a watermark", "tags": [ "catering" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.banquet_order_line/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne resource on a banquet event order — a menu, a coffee break, the room, a screen. `quantity_basis` says whether it bills per person (times the event's billable count) or as a fixed quantity; `unit_price` is in the order's currency. Posting links the line to the charge it became.", "operationId": "list_links_hospitality_banquet_order_line", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.banquet_order_line:read" ] } ], "summary": "List links of Banquet order line", "tags": [ "catering" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.banquet_order_has_line", "hospitality.link.banquet_order_line_for_service_item", "hospitality.link.banquet_order_line_posted_charge" ] } } ] }, "/v1/object-types/hospitality.banquet_order_line/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne resource on a banquet event order — a menu, a coffee break, the room, a screen. `quantity_basis` says whether it bills per person (times the event's billable count) or as a fixed quantity; `unit_price` is in the order's currency. Posting links the line to the charge it became.", "operationId": "traverse_hospitality_banquet_order_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.banquet_order_has_line", "hospitality.link.banquet_order_line_for_service_item", "hospitality.link.banquet_order_line_posted_charge" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.banquet_order_line:read" ] } ], "summary": "Traverse from Banquet order line", "tags": [ "catering" ] } }, "/v1/object-types/hospitality.banquet_order_line/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne resource on a banquet event order — a menu, a coffee break, the room, a screen. `quantity_basis` says whether it bills per person (times the event's billable count) or as a fixed quantity; `unit_price` is in the order's currency. Posting links the line to the charge it became.", "operationId": "search_hospitality_banquet_order_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sequence" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sequence" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sequence" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "category" }, "type": { "const": "eq" }, "value": { "enum": [ "room_rental", "food", "beverage", "audio_visual", "equipment", "labour", "decor", "entertainment", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quantity_basis" }, "type": { "const": "eq" }, "value": { "enum": [ "per_person", "fixed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quantity" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quantity" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quantity" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "unit_price" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "serve_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "serve_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "serve_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "sequence", "category", "description", "quantity_basis", "quantity", "serve_at", "notes" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.banquet_order_line" }, "properties": { "additionalProperties": false, "properties": { "category": { "enum": [ "room_rental", "food", "beverage", "audio_visual", "equipment", "labour", "decor", "entertainment", "other" ], "title": "Section of the sheet the line belongs to", "type": "string" }, "description": { "title": "What the line is", "type": "string" }, "id": { "title": "Line id", "type": "string" }, "notes": { "title": "Dietary, presentation, placement", "type": "string" }, "quantity": { "title": "Fixed quantity, or units per person", "type": "integer" }, "quantity_basis": { "enum": [ "per_person", "fixed" ], "title": "Per person, or a fixed quantity", "type": "string" }, "sequence": { "title": "Order of the line on the sheet", "type": "integer" }, "serve_at": { "format": "date-time", "title": "When the line is served or set", "type": "string" }, "unit_price": { "description": "Price per unit", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Banquet order line unit price", "type": "object" } }, "required": [ "id", "sequence", "category", "description", "quantity_basis", "quantity" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.banquet_order_line:read" ] } ], "summary": "Search Banquet order line", "tags": [ "catering" ] } }, "/v1/object-types/hospitality.block_allocation/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne cell of a group block's room-type x date grid. `blocked` is the UNPICKED hold — the number this block still keeps out of house availability — and `picked` counts rooms already taken up by reservations. Rooms available to the group are `blocked - picked`, derived rather than stored. `blocked_original` is the allotment as first committed and does not move, so a wash or an attrition claim always has a baseline.", "operationId": "get_hospitality_block_allocation", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.block_allocation" }, "properties": { "additionalProperties": false, "properties": { "blocked": { "title": "Rooms still held and unpicked", "type": "integer" }, "blocked_original": { "title": "Allotment as first committed", "type": "integer" }, "business_date": { "format": "date", "title": "Stay night", "type": "string" }, "id": { "title": "Allocation id", "type": "string" }, "picked": { "title": "Rooms picked up by reservations", "type": "integer" }, "rate_amount": { "description": "Per-cell rate override", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Block allocation rate amount", "type": "object" } }, "required": [ "id", "business_date", "blocked", "blocked_original", "picked" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.block_allocation:read" ] } ], "summary": "Read Block allocation", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.block_allocation/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne cell of a group block's room-type x date grid. `blocked` is the UNPICKED hold — the number this block still keeps out of house availability — and `picked` counts rooms already taken up by reservations. Rooms available to the group are `blocked - picked`, derived rather than stored. `blocked_original` is the allotment as first committed and does not move, so a wash or an attrition claim always has a baseline.", "operationId": "get_hospitality_block_allocation_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.block_allocation" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.block_allocation:read" ] } ], "summary": "Read Block allocation as of a watermark", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.block_allocation/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne cell of a group block's room-type x date grid. `blocked` is the UNPICKED hold — the number this block still keeps out of house availability — and `picked` counts rooms already taken up by reservations. Rooms available to the group are `blocked - picked`, derived rather than stored. `blocked_original` is the allotment as first committed and does not move, so a wash or an attrition claim always has a baseline.", "operationId": "list_links_hospitality_block_allocation", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.block_allocation:read" ] } ], "summary": "List links of Block allocation", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.block_allocation_for_room_type", "hospitality.link.block_allocation_of_block" ] } } ] }, "/v1/object-types/hospitality.block_allocation/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne cell of a group block's room-type x date grid. `blocked` is the UNPICKED hold — the number this block still keeps out of house availability — and `picked` counts rooms already taken up by reservations. Rooms available to the group are `blocked - picked`, derived rather than stored. `blocked_original` is the allotment as first committed and does not move, so a wash or an attrition claim always has a baseline.", "operationId": "traverse_hospitality_block_allocation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.block_allocation_for_room_type", "hospitality.link.block_allocation_of_block" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.block_allocation:read" ] } ], "summary": "Traverse from Block allocation", "tags": [ "revenue" ] } }, "/v1/object-types/hospitality.block_allocation/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne cell of a group block's room-type x date grid. `blocked` is the UNPICKED hold — the number this block still keeps out of house availability — and `picked` counts rooms already taken up by reservations. Rooms available to the group are `blocked - picked`, derived rather than stored. `blocked_original` is the allotment as first committed and does not move, so a wash or an attrition claim always has a baseline.", "operationId": "search_hospitality_block_allocation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "blocked" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "blocked" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "blocked" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "blocked_original" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "blocked_original" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "blocked_original" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "picked" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "picked" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "picked" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rate_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "business_date", "blocked", "blocked_original", "picked" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.block_allocation" }, "properties": { "additionalProperties": false, "properties": { "blocked": { "title": "Rooms still held and unpicked", "type": "integer" }, "blocked_original": { "title": "Allotment as first committed", "type": "integer" }, "business_date": { "format": "date", "title": "Stay night", "type": "string" }, "id": { "title": "Allocation id", "type": "string" }, "picked": { "title": "Rooms picked up by reservations", "type": "integer" }, "rate_amount": { "description": "Per-cell rate override", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Block allocation rate amount", "type": "object" } }, "required": [ "id", "business_date", "blocked", "blocked_original", "picked" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.block_allocation:read" ] } ], "summary": "Search Block allocation", "tags": [ "revenue" ] } }, "/v1/object-types/hospitality.board_sort_pattern/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe order a property sets for one of its boards (hubOS's server-defined sort pattern): the attendant's housekeeping sheet, the supervisor's rack, the engineer's work-order board, or the pacing report. `keys` is an ordered list — the first key decides, the next breaks its ties — each with a direction and, for a ranked key (priority, task type, status), the house's order of its values (departures before stayovers, say). One per board per house, authored by `set_board_sort_pattern` (a repeated board replaces it in place) and retired by `retire_board_sort_pattern`, which gives the board back to the kernel's default. A staff member's own preference (`staff_member.sort_preferences`) wins over it; `hospitality.function.board_sort` reads the order a caller sees.", "operationId": "get_hospitality_board_sort_pattern", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.board_sort_pattern" }, "properties": { "additionalProperties": false, "properties": { "board": { "enum": [ "housekeeping_sheet", "housekeeping_rack", "work_orders", "pacing" ], "title": "The board this pattern orders", "type": "string" }, "id": { "title": "Board sort pattern id", "type": "string" }, "keys": { "description": "The keys the board is ordered by, first key first — each a key valid for the board, a direction, and for a ranked key optionally the order of its values", "items": { "properties": { "direction": { "enum": [ "asc", "desc" ], "type": "string" }, "key": { "enum": [ "priority", "room_number", "floor", "task_type", "status", "due_at", "credits", "arrival_time", "departure_time", "pending_credits", "target_percent", "name" ], "type": "string" }, "values": { "items": { "type": "string" }, "type": "array" } }, "required": [ "key", "direction" ], "type": "object" }, "title": "Board sort pattern keys", "type": "array" }, "retired_at": { "format": "date-time", "title": "When the pattern was retired", "type": "string" }, "status": { "enum": [ "active", "retired" ], "title": "Active (orders the board) or retired (the kernel's default does)", "type": "string" } }, "required": [ "id", "board", "keys", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.board_sort_pattern:read" ] } ], "summary": "Read Board sort pattern", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.board_sort_pattern/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe order a property sets for one of its boards (hubOS's server-defined sort pattern): the attendant's housekeeping sheet, the supervisor's rack, the engineer's work-order board, or the pacing report. `keys` is an ordered list — the first key decides, the next breaks its ties — each with a direction and, for a ranked key (priority, task type, status), the house's order of its values (departures before stayovers, say). One per board per house, authored by `set_board_sort_pattern` (a repeated board replaces it in place) and retired by `retire_board_sort_pattern`, which gives the board back to the kernel's default. A staff member's own preference (`staff_member.sort_preferences`) wins over it; `hospitality.function.board_sort` reads the order a caller sees.", "operationId": "get_hospitality_board_sort_pattern_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.board_sort_pattern" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.board_sort_pattern:read" ] } ], "summary": "Read Board sort pattern as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.board_sort_pattern/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe order a property sets for one of its boards (hubOS's server-defined sort pattern): the attendant's housekeeping sheet, the supervisor's rack, the engineer's work-order board, or the pacing report. `keys` is an ordered list — the first key decides, the next breaks its ties — each with a direction and, for a ranked key (priority, task type, status), the house's order of its values (departures before stayovers, say). One per board per house, authored by `set_board_sort_pattern` (a repeated board replaces it in place) and retired by `retire_board_sort_pattern`, which gives the board back to the kernel's default. A staff member's own preference (`staff_member.sort_preferences`) wins over it; `hospitality.function.board_sort` reads the order a caller sees.", "operationId": "list_links_hospitality_board_sort_pattern", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.board_sort_pattern:read" ] } ], "summary": "List links of Board sort pattern", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.board_sort_pattern_at_property" ] } } ] }, "/v1/object-types/hospitality.board_sort_pattern/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe order a property sets for one of its boards (hubOS's server-defined sort pattern): the attendant's housekeeping sheet, the supervisor's rack, the engineer's work-order board, or the pacing report. `keys` is an ordered list — the first key decides, the next breaks its ties — each with a direction and, for a ranked key (priority, task type, status), the house's order of its values (departures before stayovers, say). One per board per house, authored by `set_board_sort_pattern` (a repeated board replaces it in place) and retired by `retire_board_sort_pattern`, which gives the board back to the kernel's default. A staff member's own preference (`staff_member.sort_preferences`) wins over it; `hospitality.function.board_sort` reads the order a caller sees.", "operationId": "traverse_hospitality_board_sort_pattern", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.board_sort_pattern_at_property" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.board_sort_pattern:read" ] } ], "summary": "Traverse from Board sort pattern", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.board_sort_pattern/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe order a property sets for one of its boards (hubOS's server-defined sort pattern): the attendant's housekeeping sheet, the supervisor's rack, the engineer's work-order board, or the pacing report. `keys` is an ordered list — the first key decides, the next breaks its ties — each with a direction and, for a ranked key (priority, task type, status), the house's order of its values (departures before stayovers, say). One per board per house, authored by `set_board_sort_pattern` (a repeated board replaces it in place) and retired by `retire_board_sort_pattern`, which gives the board back to the kernel's default. A staff member's own preference (`staff_member.sort_preferences`) wins over it; `hospitality.function.board_sort` reads the order a caller sees.", "operationId": "search_hospitality_board_sort_pattern", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "board" }, "type": { "const": "eq" }, "value": { "enum": [ "housekeeping_sheet", "housekeeping_rack", "work_orders", "pacing" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "keys" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "direction": { "enum": [ "asc", "desc" ], "type": "string" }, "key": { "enum": [ "priority", "room_number", "floor", "task_type", "status", "due_at", "credits", "arrival_time", "departure_time", "pending_credits", "target_percent", "name" ], "type": "string" }, "values": { "items": { "type": "string" }, "type": "array" } }, "required": [ "key", "direction" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "retired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "board", "status", "retired_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.board_sort_pattern" }, "properties": { "additionalProperties": false, "properties": { "board": { "enum": [ "housekeeping_sheet", "housekeeping_rack", "work_orders", "pacing" ], "title": "The board this pattern orders", "type": "string" }, "id": { "title": "Board sort pattern id", "type": "string" }, "keys": { "description": "The keys the board is ordered by, first key first — each a key valid for the board, a direction, and for a ranked key optionally the order of its values", "items": { "properties": { "direction": { "enum": [ "asc", "desc" ], "type": "string" }, "key": { "enum": [ "priority", "room_number", "floor", "task_type", "status", "due_at", "credits", "arrival_time", "departure_time", "pending_credits", "target_percent", "name" ], "type": "string" }, "values": { "items": { "type": "string" }, "type": "array" } }, "required": [ "key", "direction" ], "type": "object" }, "title": "Board sort pattern keys", "type": "array" }, "retired_at": { "format": "date-time", "title": "When the pattern was retired", "type": "string" }, "status": { "enum": [ "active", "retired" ], "title": "Active (orders the board) or retired (the kernel's default does)", "type": "string" } }, "required": [ "id", "board", "keys", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.board_sort_pattern:read" ] } ], "summary": "Search Board sort pattern", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.booking_origin/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe IP address and device a guest booked from, captured only for a booking the guest made online themselves (`source = direct_web`). Card-network evidence for a fraud chargeback (Visa Compelling Evidence 3.0); kept apart from the reservation so its own retention clock applies and its values never travel in an event image.", "operationId": "get_hospitality_booking_origin", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.booking_origin" }, "properties": { "additionalProperties": false, "properties": { "captured_at": { "format": "date-time", "title": "When the booking engine saw the guest book", "type": "string" }, "device_id": { "title": "A stable identifier for the device the booking was made on, as the booking engine assigns it. Visa counts device id or device fingerprint as one element, never both.", "type": "string" }, "id": { "title": "Origin record id", "type": "string" }, "ip_address": { "title": "The IP address the booking was made from, as the booking engine saw it (IPv4 or IPv6, canonical form)", "type": "string" }, "retain_until": { "format": "date", "title": "Storage-limitation clock: captured_at plus 485 days, the 364-day CE 3.0 lookback and the 120-day window for a dispute to arrive. The same discipline `payment_card` and `guest_id_document` carry.", "type": "string" } }, "required": [ "id", "captured_at", "retain_until" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.booking_origin:read" ] } ], "summary": "Read Booking origin", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.booking_origin/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe IP address and device a guest booked from, captured only for a booking the guest made online themselves (`source = direct_web`). Card-network evidence for a fraud chargeback (Visa Compelling Evidence 3.0); kept apart from the reservation so its own retention clock applies and its values never travel in an event image.", "operationId": "get_hospitality_booking_origin_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.booking_origin" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.booking_origin:read" ] } ], "summary": "Read Booking origin as of a watermark", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.booking_origin/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe IP address and device a guest booked from, captured only for a booking the guest made online themselves (`source = direct_web`). Card-network evidence for a fraud chargeback (Visa Compelling Evidence 3.0); kept apart from the reservation so its own retention clock applies and its values never travel in an event image.", "operationId": "list_links_hospitality_booking_origin", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.booking_origin:read" ] } ], "summary": "List links of Booking origin", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.booking_origin_for_reservation" ] } } ] }, "/v1/object-types/hospitality.booking_origin/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe IP address and device a guest booked from, captured only for a booking the guest made online themselves (`source = direct_web`). Card-network evidence for a fraud chargeback (Visa Compelling Evidence 3.0); kept apart from the reservation so its own retention clock applies and its values never travel in an event image.", "operationId": "traverse_hospitality_booking_origin", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.booking_origin_for_reservation" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.booking_origin:read" ] } ], "summary": "Traverse from Booking origin", "tags": [ "booking" ] } }, "/v1/object-types/hospitality.booking_origin/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe IP address and device a guest booked from, captured only for a booking the guest made online themselves (`source = direct_web`). Card-network evidence for a fraud chargeback (Visa Compelling Evidence 3.0); kept apart from the reservation so its own retention clock applies and its values never travel in an event image.", "operationId": "search_hospitality_booking_origin", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ip_address" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ip_address" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ip_address" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ip_address" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "device_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "device_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "device_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "device_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "captured_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "captured_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "captured_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retain_until" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retain_until" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retain_until" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "ip_address", "device_id", "captured_at", "retain_until" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.booking_origin" }, "properties": { "additionalProperties": false, "properties": { "captured_at": { "format": "date-time", "title": "When the booking engine saw the guest book", "type": "string" }, "device_id": { "title": "A stable identifier for the device the booking was made on, as the booking engine assigns it. Visa counts device id or device fingerprint as one element, never both.", "type": "string" }, "id": { "title": "Origin record id", "type": "string" }, "ip_address": { "title": "The IP address the booking was made from, as the booking engine saw it (IPv4 or IPv6, canonical form)", "type": "string" }, "retain_until": { "format": "date", "title": "Storage-limitation clock: captured_at plus 485 days, the 364-day CE 3.0 lookback and the 120-day window for a dispute to arrive. The same discipline `payment_card` and `guest_id_document` carry.", "type": "string" } }, "required": [ "id", "captured_at", "retain_until" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.booking_origin:read" ] } ], "summary": "Search Booking origin", "tags": [ "booking" ] } }, "/v1/object-types/hospitality.brand/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA hospitality brand. Used by enterprise tenants that operate multiple properties under a shared name and standards. Boutique tenants typically have zero or one Brand.", "operationId": "get_hospitality_brand", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.brand" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Brand code", "type": "string" }, "description": { "title": "Description", "type": "string" }, "founded": { "format": "date", "title": "Founded", "type": "string" }, "name": { "title": "Brand name", "type": "string" }, "segment": { "enum": [ "luxury", "upper_upscale", "upscale", "upper_midscale", "midscale", "economy", "lifestyle", "boutique", "resort", "mixed" ], "title": "Segment", "type": "string" }, "website": { "title": "Website", "type": "string" } }, "required": [ "code", "name" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.brand:read" ] } ], "summary": "Read Brand", "tags": [ "organization" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.brand/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA hospitality brand. Used by enterprise tenants that operate multiple properties under a shared name and standards. Boutique tenants typically have zero or one Brand.", "operationId": "get_hospitality_brand_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.brand" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.brand:read" ] } ], "summary": "Read Brand as of a watermark", "tags": [ "organization" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.brand/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA hospitality brand. Used by enterprise tenants that operate multiple properties under a shared name and standards. Boutique tenants typically have zero or one Brand.", "operationId": "list_links_hospitality_brand", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.brand:read" ] } ], "summary": "List links of Brand", "tags": [ "organization" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.brand_has_portfolio", "hospitality.link.brand_has_property", "hospitality.link.brand_has_rate_plan", "hospitality.link.cancellation_policy_at_brand", "hospitality.link.checklist_template_at_brand", "hospitality.link.development_pathway_definition_at_brand", "hospitality.link.fault_type_at_brand", "hospitality.link.ingredient_at_brand", "hospitality.link.loyalty_program_at_brand", "hospitality.link.material_at_brand", "hospitality.link.package_at_brand", "hospitality.link.recipe_at_brand", "hospitality.link.retail_product_line_has_brand_parent", "hospitality.link.venue_brand_has_parent_brand" ] } } ] }, "/v1/object-types/hospitality.brand/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA hospitality brand. Used by enterprise tenants that operate multiple properties under a shared name and standards. Boutique tenants typically have zero or one Brand.", "operationId": "traverse_hospitality_brand", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.brand_has_portfolio", "hospitality.link.brand_has_property", "hospitality.link.brand_has_rate_plan", "hospitality.link.cancellation_policy_at_brand", "hospitality.link.checklist_template_at_brand", "hospitality.link.development_pathway_definition_at_brand", "hospitality.link.fault_type_at_brand", "hospitality.link.ingredient_at_brand", "hospitality.link.loyalty_program_at_brand", "hospitality.link.material_at_brand", "hospitality.link.package_at_brand", "hospitality.link.recipe_at_brand", "hospitality.link.retail_product_line_has_brand_parent", "hospitality.link.venue_brand_has_parent_brand" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.brand:read" ] } ], "summary": "Traverse from Brand", "tags": [ "organization" ] } }, "/v1/object-types/hospitality.brand/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA hospitality brand. Used by enterprise tenants that operate multiple properties under a shared name and standards. Boutique tenants typically have zero or one Brand.", "operationId": "search_hospitality_brand", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "website" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "website" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "website" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "website" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "founded" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "founded" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "founded" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "segment" }, "type": { "const": "eq" }, "value": { "enum": [ "luxury", "upper_upscale", "upscale", "upper_midscale", "midscale", "economy", "lifestyle", "boutique", "resort", "mixed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "description", "website", "founded", "segment" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.brand" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Brand code", "type": "string" }, "description": { "title": "Description", "type": "string" }, "founded": { "format": "date", "title": "Founded", "type": "string" }, "name": { "title": "Brand name", "type": "string" }, "segment": { "enum": [ "luxury", "upper_upscale", "upscale", "upper_midscale", "midscale", "economy", "lifestyle", "boutique", "resort", "mixed" ], "title": "Segment", "type": "string" }, "website": { "title": "Website", "type": "string" } }, "required": [ "code", "name" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.brand:read" ] } ], "summary": "Search Brand", "tags": [ "organization" ] } }, "/v1/object-types/hospitality.brand_operator_cost_entry/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne posted mandatory brand/operator charge (USALI 12 Schedule 16) — royalty, marketing assessment, loyalty, reservations, technology, training, purchasing, QA, or management fee. Only mandatory charges; optional services and pass-throughs are excluded by Schedule 16's definition. Immutable except the terminal void.", "operationId": "get_hospitality_brand_operator_cost_entry", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.brand_operator_cost_entry" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "Amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Brand & operator cost entry amount", "type": "object" }, "business_date": { "format": "date", "title": "Business date", "type": "string" }, "counterparty": { "enum": [ "brand", "operator" ], "title": "Counterparty (brand | operator)", "type": "string" }, "external_ref": { "title": "External ref", "type": "string" }, "id": { "title": "Entry id", "type": "string" }, "kind": { "enum": [ "royalty_fee", "brand_marketing_assessment", "loyalty_program_fee", "reservation_fee", "technology_fee", "training_fee", "purchasing_program_fee", "payroll_hr_services_fee", "quality_assurance_fee", "base_management_fee", "incentive_management_fee", "other_mandatory_cost" ], "title": "USALI Schedule 16 line", "type": "string" }, "period_end": { "format": "date", "title": "Invoice-period end", "type": "string" }, "period_start": { "format": "date", "title": "Invoice-period start", "type": "string" }, "posted_at": { "format": "date-time", "title": "Posted at", "type": "string" }, "source": { "enum": [ "invoice_import", "manual" ], "title": "Source", "type": "string" }, "voided": { "title": "Voided", "type": "boolean" } }, "required": [ "id", "kind", "counterparty", "business_date", "source", "posted_at", "voided" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.brand_operator_cost_entry:read" ] } ], "summary": "Read Brand & operator cost entry", "tags": [ "brand_operator" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.brand_operator_cost_entry/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne posted mandatory brand/operator charge (USALI 12 Schedule 16) — royalty, marketing assessment, loyalty, reservations, technology, training, purchasing, QA, or management fee. Only mandatory charges; optional services and pass-throughs are excluded by Schedule 16's definition. Immutable except the terminal void.", "operationId": "get_hospitality_brand_operator_cost_entry_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.brand_operator_cost_entry" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.brand_operator_cost_entry:read" ] } ], "summary": "Read Brand & operator cost entry as of a watermark", "tags": [ "brand_operator" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.brand_operator_cost_entry/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne posted mandatory brand/operator charge (USALI 12 Schedule 16) — royalty, marketing assessment, loyalty, reservations, technology, training, purchasing, QA, or management fee. Only mandatory charges; optional services and pass-throughs are excluded by Schedule 16's definition. Immutable except the terminal void.", "operationId": "list_links_hospitality_brand_operator_cost_entry", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.brand_operator_cost_entry:read" ] } ], "summary": "List links of Brand & operator cost entry", "tags": [ "brand_operator" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.brand_operator_cost_at_property", "hospitality.link.brand_operator_cost_for_company" ] } } ] }, "/v1/object-types/hospitality.brand_operator_cost_entry/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne posted mandatory brand/operator charge (USALI 12 Schedule 16) — royalty, marketing assessment, loyalty, reservations, technology, training, purchasing, QA, or management fee. Only mandatory charges; optional services and pass-throughs are excluded by Schedule 16's definition. Immutable except the terminal void.", "operationId": "traverse_hospitality_brand_operator_cost_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.brand_operator_cost_at_property", "hospitality.link.brand_operator_cost_for_company" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.brand_operator_cost_entry:read" ] } ], "summary": "Traverse from Brand & operator cost entry", "tags": [ "brand_operator" ] } }, "/v1/object-types/hospitality.brand_operator_cost_entry/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne posted mandatory brand/operator charge (USALI 12 Schedule 16) — royalty, marketing assessment, loyalty, reservations, technology, training, purchasing, QA, or management fee. Only mandatory charges; optional services and pass-throughs are excluded by Schedule 16's definition. Immutable except the terminal void.", "operationId": "search_hospitality_brand_operator_cost_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "royalty_fee", "brand_marketing_assessment", "loyalty_program_fee", "reservation_fee", "technology_fee", "training_fee", "purchasing_program_fee", "payroll_hr_services_fee", "quality_assurance_fee", "base_management_fee", "incentive_management_fee", "other_mandatory_cost" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "counterparty" }, "type": { "const": "eq" }, "value": { "enum": [ "brand", "operator" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_start" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_start" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_start" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_end" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_end" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_end" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source" }, "type": { "const": "eq" }, "value": { "enum": [ "invoice_import", "manual" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "posted_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "posted_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "posted_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "voided" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "kind", "counterparty", "business_date", "period_start", "period_end", "source", "external_ref", "posted_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.brand_operator_cost_entry" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "Amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Brand & operator cost entry amount", "type": "object" }, "business_date": { "format": "date", "title": "Business date", "type": "string" }, "counterparty": { "enum": [ "brand", "operator" ], "title": "Counterparty (brand | operator)", "type": "string" }, "external_ref": { "title": "External ref", "type": "string" }, "id": { "title": "Entry id", "type": "string" }, "kind": { "enum": [ "royalty_fee", "brand_marketing_assessment", "loyalty_program_fee", "reservation_fee", "technology_fee", "training_fee", "purchasing_program_fee", "payroll_hr_services_fee", "quality_assurance_fee", "base_management_fee", "incentive_management_fee", "other_mandatory_cost" ], "title": "USALI Schedule 16 line", "type": "string" }, "period_end": { "format": "date", "title": "Invoice-period end", "type": "string" }, "period_start": { "format": "date", "title": "Invoice-period start", "type": "string" }, "posted_at": { "format": "date-time", "title": "Posted at", "type": "string" }, "source": { "enum": [ "invoice_import", "manual" ], "title": "Source", "type": "string" }, "voided": { "title": "Voided", "type": "boolean" } }, "required": [ "id", "kind", "counterparty", "business_date", "source", "posted_at", "voided" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.brand_operator_cost_entry:read" ] } ], "summary": "Search Brand & operator cost entry", "tags": [ "brand_operator" ] } }, "/v1/object-types/hospitality.business_date/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe property's accounting day. Created when the property opens the day, closed by the night-audit run. Most operational objects (charges, room postings, restrictions) attach to a business date rather than to wall-clock UTC.", "operationId": "get_hospitality_business_date", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.business_date" }, "properties": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" }, "closed_at": { "format": "date-time", "title": "Closed at (UTC)", "type": "string" }, "opened_at": { "format": "date-time", "title": "Opened at (UTC)", "type": "string" }, "status": { "enum": [ "open", "closing", "closed" ], "title": "Status", "type": "string" } }, "required": [ "business_date", "status", "opened_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.business_date:read" ] } ], "summary": "Read Business date", "tags": [ "audit" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.business_date/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe property's accounting day. Created when the property opens the day, closed by the night-audit run. Most operational objects (charges, room postings, restrictions) attach to a business date rather than to wall-clock UTC.", "operationId": "get_hospitality_business_date_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.business_date" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.business_date:read" ] } ], "summary": "Read Business date as of a watermark", "tags": [ "audit" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.business_date/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe property's accounting day. Created when the property opens the day, closed by the night-audit run. Most operational objects (charges, room postings, restrictions) attach to a business date rather than to wall-clock UTC.", "operationId": "list_links_hospitality_business_date", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.business_date:read" ] } ], "summary": "List links of Business date", "tags": [ "audit" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.night_audit_run_for_business_date", "hospitality.link.property_has_business_date" ] } } ] }, "/v1/object-types/hospitality.business_date/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe property's accounting day. Created when the property opens the day, closed by the night-audit run. Most operational objects (charges, room postings, restrictions) attach to a business date rather than to wall-clock UTC.", "operationId": "traverse_hospitality_business_date", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.night_audit_run_for_business_date", "hospitality.link.property_has_business_date" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.business_date:read" ] } ], "summary": "Traverse from Business date", "tags": [ "audit" ] } }, "/v1/object-types/hospitality.business_date/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe property's accounting day. Created when the property opens the day, closed by the night-audit run. Most operational objects (charges, room postings, restrictions) attach to a business date rather than to wall-clock UTC.", "operationId": "search_hospitality_business_date", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "open", "closing", "closed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "business_date", "status", "opened_at", "closed_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.business_date" }, "properties": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" }, "closed_at": { "format": "date-time", "title": "Closed at (UTC)", "type": "string" }, "opened_at": { "format": "date-time", "title": "Opened at (UTC)", "type": "string" }, "status": { "enum": [ "open", "closing", "closed" ], "title": "Status", "type": "string" } }, "required": [ "business_date", "status", "opened_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.business_date:read" ] } ], "summary": "Search Business date", "tags": [ "audit" ] } }, "/v1/object-types/hospitality.cancellation_policy/objects/{id}": { "get": { "description": "Read an existing instance.\n\nStructured cancellation terms — an ordered penalty ladder keyed on hours-before-arrival, plus the no-show carve-out and the notice-window clock basis. Reservations bind both a live `cancellation_policy_ref` and a `cancellation_policy_text` snapshot at booking time per the structured-policy + immutable-snapshot pattern (design-spec §B.2). Brand-standard policies live at brand; bespoke / property-specific at property. Non-refundable advance-purchase rates ship with empty `tiers`, `non_refundable = true`, and `applies_to_no_show = always_100_percent`.", "operationId": "get_hospitality_cancellation_policy", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.cancellation_policy" }, "properties": { "additionalProperties": false, "properties": { "applies_to_no_show": { "enum": [ "inherit_last_tier", "separate_no_show_tier", "always_100_percent" ], "title": "No-show handling", "type": "string" }, "code": { "title": "Policy code", "type": "string" }, "currency": { "format": "iso-4217", "title": "Currency (ISO 4217)", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "name": { "title": "Display name", "type": "string" }, "non_refundable": { "title": "Non-refundable (advance-purchase shape)", "type": "boolean" }, "notice_window_basis": { "enum": [ "local_property_time", "guest_local_time", "utc" ], "title": "Notice-window clock basis", "type": "string" }, "tiers": { "description": "Penalty tier ladder (sorted descending by trigger offset)", "items": { "properties": { "applies_to": { "enum": [ "cancellation", "no_show", "both" ], "type": "string" }, "penalty_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "penalty_kind": { "enum": [ "absolute", "percent_of_total", "n_nights" ], "type": "string" }, "penalty_nights": { "type": "integer" }, "penalty_rate": { "format": "decimal", "type": "string" }, "trigger_offset_hours_before_arrival": { "type": "integer" } }, "required": [ "trigger_offset_hours_before_arrival", "penalty_kind", "applies_to" ], "type": "object" }, "title": "Cancellation policy tiers", "type": "array" } }, "required": [ "code", "name", "non_refundable", "currency", "tiers", "applies_to_no_show", "notice_window_basis" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.cancellation_policy:read" ] } ], "summary": "Read Cancellation policy", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.cancellation_policy/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nStructured cancellation terms — an ordered penalty ladder keyed on hours-before-arrival, plus the no-show carve-out and the notice-window clock basis. Reservations bind both a live `cancellation_policy_ref` and a `cancellation_policy_text` snapshot at booking time per the structured-policy + immutable-snapshot pattern (design-spec §B.2). Brand-standard policies live at brand; bespoke / property-specific at property. Non-refundable advance-purchase rates ship with empty `tiers`, `non_refundable = true`, and `applies_to_no_show = always_100_percent`.", "operationId": "get_hospitality_cancellation_policy_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.cancellation_policy" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.cancellation_policy:read" ] } ], "summary": "Read Cancellation policy as of a watermark", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.cancellation_policy/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nStructured cancellation terms — an ordered penalty ladder keyed on hours-before-arrival, plus the no-show carve-out and the notice-window clock basis. Reservations bind both a live `cancellation_policy_ref` and a `cancellation_policy_text` snapshot at booking time per the structured-policy + immutable-snapshot pattern (design-spec §B.2). Brand-standard policies live at brand; bespoke / property-specific at property. Non-refundable advance-purchase rates ship with empty `tiers`, `non_refundable = true`, and `applies_to_no_show = always_100_percent`.", "operationId": "list_links_hospitality_cancellation_policy", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.cancellation_policy:read" ] } ], "summary": "List links of Cancellation policy", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.cancellation_policy_at_brand", "hospitality.link.cancellation_policy_at_property", "hospitality.link.rate_plan_requires_cancellation_policy", "hospitality.link.reservation_uses_cancellation_policy" ] } } ] }, "/v1/object-types/hospitality.cancellation_policy/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nStructured cancellation terms — an ordered penalty ladder keyed on hours-before-arrival, plus the no-show carve-out and the notice-window clock basis. Reservations bind both a live `cancellation_policy_ref` and a `cancellation_policy_text` snapshot at booking time per the structured-policy + immutable-snapshot pattern (design-spec §B.2). Brand-standard policies live at brand; bespoke / property-specific at property. Non-refundable advance-purchase rates ship with empty `tiers`, `non_refundable = true`, and `applies_to_no_show = always_100_percent`.", "operationId": "traverse_hospitality_cancellation_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.cancellation_policy_at_brand", "hospitality.link.cancellation_policy_at_property", "hospitality.link.rate_plan_requires_cancellation_policy", "hospitality.link.reservation_uses_cancellation_policy" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.cancellation_policy:read" ] } ], "summary": "Traverse from Cancellation policy", "tags": [ "booking" ] } }, "/v1/object-types/hospitality.cancellation_policy/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nStructured cancellation terms — an ordered penalty ladder keyed on hours-before-arrival, plus the no-show carve-out and the notice-window clock basis. Reservations bind both a live `cancellation_policy_ref` and a `cancellation_policy_text` snapshot at booking time per the structured-policy + immutable-snapshot pattern (design-spec §B.2). Brand-standard policies live at brand; bespoke / property-specific at property. Non-refundable advance-purchase rates ship with empty `tiers`, `non_refundable = true`, and `applies_to_no_show = always_100_percent`.", "operationId": "search_hospitality_cancellation_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "non_refundable" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "currency" }, "type": { "const": "eq" }, "value": { "format": "iso-4217", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tiers" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "applies_to": { "enum": [ "cancellation", "no_show", "both" ], "type": "string" }, "penalty_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "penalty_kind": { "enum": [ "absolute", "percent_of_total", "n_nights" ], "type": "string" }, "penalty_nights": { "type": "integer" }, "penalty_rate": { "format": "decimal", "type": "string" }, "trigger_offset_hours_before_arrival": { "type": "integer" } }, "required": [ "trigger_offset_hours_before_arrival", "penalty_kind", "applies_to" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applies_to_no_show" }, "type": { "const": "eq" }, "value": { "enum": [ "inherit_last_tier", "separate_no_show_tier", "always_100_percent" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notice_window_basis" }, "type": { "const": "eq" }, "value": { "enum": [ "local_property_time", "guest_local_time", "utc" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "description", "applies_to_no_show", "notice_window_basis" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.cancellation_policy" }, "properties": { "additionalProperties": false, "properties": { "applies_to_no_show": { "enum": [ "inherit_last_tier", "separate_no_show_tier", "always_100_percent" ], "title": "No-show handling", "type": "string" }, "code": { "title": "Policy code", "type": "string" }, "currency": { "format": "iso-4217", "title": "Currency (ISO 4217)", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "name": { "title": "Display name", "type": "string" }, "non_refundable": { "title": "Non-refundable (advance-purchase shape)", "type": "boolean" }, "notice_window_basis": { "enum": [ "local_property_time", "guest_local_time", "utc" ], "title": "Notice-window clock basis", "type": "string" }, "tiers": { "description": "Penalty tier ladder (sorted descending by trigger offset)", "items": { "properties": { "applies_to": { "enum": [ "cancellation", "no_show", "both" ], "type": "string" }, "penalty_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "penalty_kind": { "enum": [ "absolute", "percent_of_total", "n_nights" ], "type": "string" }, "penalty_nights": { "type": "integer" }, "penalty_rate": { "format": "decimal", "type": "string" }, "trigger_offset_hours_before_arrival": { "type": "integer" } }, "required": [ "trigger_offset_hours_before_arrival", "penalty_kind", "applies_to" ], "type": "object" }, "title": "Cancellation policy tiers", "type": "array" } }, "required": [ "code", "name", "non_refundable", "currency", "tiers", "applies_to_no_show", "notice_window_basis" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.cancellation_policy:read" ] } ], "summary": "Search Cancellation policy", "tags": [ "booking" ] } }, "/v1/object-types/hospitality.cashier/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA cash drawer's identity at one property — the till that shifts open against and cash movements reconcile to. Mews's cashier without the user-assignment mirror; OPERA's cashier ID without the PIN ceremony. Retire a cashier rather than deleting it: closed sessions keep pointing at the till they reconciled.", "operationId": "get_hospitality_cashier", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.cashier" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Cashier code", "type": "string" }, "name": { "title": "Cashier name", "type": "string" }, "notes": { "title": "Notes", "type": "string" }, "status": { "enum": [ "active", "retired" ], "title": "Status", "type": "string" } }, "required": [ "code", "name", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.cashier:read" ] } ], "summary": "Read Cashier", "tags": [ "cashiering" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.cashier/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA cash drawer's identity at one property — the till that shifts open against and cash movements reconcile to. Mews's cashier without the user-assignment mirror; OPERA's cashier ID without the PIN ceremony. Retire a cashier rather than deleting it: closed sessions keep pointing at the till they reconciled.", "operationId": "get_hospitality_cashier_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.cashier" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.cashier:read" ] } ], "summary": "Read Cashier as of a watermark", "tags": [ "cashiering" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.cashier/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA cash drawer's identity at one property — the till that shifts open against and cash movements reconcile to. Mews's cashier without the user-assignment mirror; OPERA's cashier ID without the PIN ceremony. Retire a cashier rather than deleting it: closed sessions keep pointing at the till they reconciled.", "operationId": "list_links_hospitality_cashier", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.cashier:read" ] } ], "summary": "List links of Cashier", "tags": [ "cashiering" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.cashier_at_property", "hospitality.link.cashier_session_for_cashier" ] } } ] }, "/v1/object-types/hospitality.cashier/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA cash drawer's identity at one property — the till that shifts open against and cash movements reconcile to. Mews's cashier without the user-assignment mirror; OPERA's cashier ID without the PIN ceremony. Retire a cashier rather than deleting it: closed sessions keep pointing at the till they reconciled.", "operationId": "traverse_hospitality_cashier", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.cashier_at_property", "hospitality.link.cashier_session_for_cashier" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.cashier:read" ] } ], "summary": "Traverse from Cashier", "tags": [ "cashiering" ] } }, "/v1/object-types/hospitality.cashier/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA cash drawer's identity at one property — the till that shifts open against and cash movements reconcile to. Mews's cashier without the user-assignment mirror; OPERA's cashier ID without the PIN ceremony. Retire a cashier rather than deleting it: closed sessions keep pointing at the till they reconciled.", "operationId": "search_hospitality_cashier", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "retired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "status", "notes" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.cashier" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Cashier code", "type": "string" }, "name": { "title": "Cashier name", "type": "string" }, "notes": { "title": "Notes", "type": "string" }, "status": { "enum": [ "active", "retired" ], "title": "Status", "type": "string" } }, "required": [ "code", "name", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.cashier:read" ] } ], "summary": "Search Cashier", "tags": [ "cashiering" ] } }, "/v1/object-types/hospitality.cashier_session/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne cash shift against a cashier: opens with a float, accumulates typed cash movements, and closes against an operator count. Expected balance = opening float + cash in - cash out; variance = counted - expected, recorded as declared data (the over/short), never a GL posting. Single-currency by design — a multi-currency desk opens one session per currency. Closed sessions are immutable; corrections are compensating transactions in the next session.", "operationId": "get_hospitality_cashier_session", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.cashier_session" }, "properties": { "additionalProperties": false, "properties": { "closed_at": { "format": "date-time", "title": "Closed at", "type": "string" }, "counted_amount": { "description": "Counted at close", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Cashier session counted amount", "type": "object" }, "currency": { "format": "iso-4217", "title": "Session currency (ISO 4217)", "type": "string" }, "expected_amount": { "description": "Expected at close", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Cashier session expected amount", "type": "object" }, "id": { "title": "Cashier session id", "type": "string" }, "notes": { "title": "Notes", "type": "string" }, "opened_at": { "format": "date-time", "title": "Opened at", "type": "string" }, "opening_float": { "description": "Opening float", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Cashier session opening float", "type": "object" }, "status": { "enum": [ "open", "closed" ], "title": "Status", "type": "string" }, "variance": { "description": "Variance at close", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Cashier session variance", "type": "object" } }, "required": [ "id", "status", "currency", "opened_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.cashier_session:read" ] } ], "summary": "Read Cashier session", "tags": [ "cashiering" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.cashier_session/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne cash shift against a cashier: opens with a float, accumulates typed cash movements, and closes against an operator count. Expected balance = opening float + cash in - cash out; variance = counted - expected, recorded as declared data (the over/short), never a GL posting. Single-currency by design — a multi-currency desk opens one session per currency. Closed sessions are immutable; corrections are compensating transactions in the next session.", "operationId": "get_hospitality_cashier_session_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.cashier_session" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.cashier_session:read" ] } ], "summary": "Read Cashier session as of a watermark", "tags": [ "cashiering" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.cashier_session/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne cash shift against a cashier: opens with a float, accumulates typed cash movements, and closes against an operator count. Expected balance = opening float + cash in - cash out; variance = counted - expected, recorded as declared data (the over/short), never a GL posting. Single-currency by design — a multi-currency desk opens one session per currency. Closed sessions are immutable; corrections are compensating transactions in the next session.", "operationId": "list_links_hospitality_cashier_session", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.cashier_session:read" ] } ], "summary": "List links of Cashier session", "tags": [ "cashiering" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.cashier_session_for_cashier", "hospitality.link.cashier_transaction_in_session" ] } } ] }, "/v1/object-types/hospitality.cashier_session/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne cash shift against a cashier: opens with a float, accumulates typed cash movements, and closes against an operator count. Expected balance = opening float + cash in - cash out; variance = counted - expected, recorded as declared data (the over/short), never a GL posting. Single-currency by design — a multi-currency desk opens one session per currency. Closed sessions are immutable; corrections are compensating transactions in the next session.", "operationId": "traverse_hospitality_cashier_session", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.cashier_session_for_cashier", "hospitality.link.cashier_transaction_in_session" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.cashier_session:read" ] } ], "summary": "Traverse from Cashier session", "tags": [ "cashiering" ] } }, "/v1/object-types/hospitality.cashier_session/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne cash shift against a cashier: opens with a float, accumulates typed cash movements, and closes against an operator count. Expected balance = opening float + cash in - cash out; variance = counted - expected, recorded as declared data (the over/short), never a GL posting. Single-currency by design — a multi-currency desk opens one session per currency. Closed sessions are immutable; corrections are compensating transactions in the next session.", "operationId": "search_hospitality_cashier_session", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "open", "closed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "currency" }, "type": { "const": "eq" }, "value": { "format": "iso-4217", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opening_float" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "counted_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expected_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "variance" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "status", "opened_at", "closed_at", "notes" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.cashier_session" }, "properties": { "additionalProperties": false, "properties": { "closed_at": { "format": "date-time", "title": "Closed at", "type": "string" }, "counted_amount": { "description": "Counted at close", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Cashier session counted amount", "type": "object" }, "currency": { "format": "iso-4217", "title": "Session currency (ISO 4217)", "type": "string" }, "expected_amount": { "description": "Expected at close", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Cashier session expected amount", "type": "object" }, "id": { "title": "Cashier session id", "type": "string" }, "notes": { "title": "Notes", "type": "string" }, "opened_at": { "format": "date-time", "title": "Opened at", "type": "string" }, "opening_float": { "description": "Opening float", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Cashier session opening float", "type": "object" }, "status": { "enum": [ "open", "closed" ], "title": "Status", "type": "string" }, "variance": { "description": "Variance at close", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Cashier session variance", "type": "object" } }, "required": [ "id", "status", "currency", "opened_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.cashier_session:read" ] } ], "summary": "Search Cashier session", "tags": [ "cashiering" ] } }, "/v1/object-types/hospitality.cashier_transaction/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne typed cash movement in a cashier session — cash_in, cash_out, tip_out, expense (OPERA's paid-out), or float_adjustment. Amounts are non-negative; the kind carries the direction. Append-only: corrections are compensating entries, never edits. Optionally mirrors a folio payment through cashier_transaction_mirrors_payment — the drawer entry is the mirror, the payment stays the ledger truth.", "operationId": "get_hospitality_cashier_transaction", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.cashier_transaction" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "Amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Cashier transaction amount", "type": "object" }, "id": { "title": "Cashier transaction id", "type": "string" }, "kind": { "enum": [ "cash_in", "cash_out", "tip_out", "expense", "float_adjustment" ], "title": "Movement kind", "type": "string" }, "notes": { "title": "Notes (the reason for the movement)", "type": "string" }, "occurred_at": { "format": "date-time", "title": "Occurred at", "type": "string" } }, "required": [ "id", "kind", "occurred_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.cashier_transaction:read" ] } ], "summary": "Read Cashier transaction", "tags": [ "cashiering" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.cashier_transaction/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne typed cash movement in a cashier session — cash_in, cash_out, tip_out, expense (OPERA's paid-out), or float_adjustment. Amounts are non-negative; the kind carries the direction. Append-only: corrections are compensating entries, never edits. Optionally mirrors a folio payment through cashier_transaction_mirrors_payment — the drawer entry is the mirror, the payment stays the ledger truth.", "operationId": "get_hospitality_cashier_transaction_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.cashier_transaction" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.cashier_transaction:read" ] } ], "summary": "Read Cashier transaction as of a watermark", "tags": [ "cashiering" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.cashier_transaction/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne typed cash movement in a cashier session — cash_in, cash_out, tip_out, expense (OPERA's paid-out), or float_adjustment. Amounts are non-negative; the kind carries the direction. Append-only: corrections are compensating entries, never edits. Optionally mirrors a folio payment through cashier_transaction_mirrors_payment — the drawer entry is the mirror, the payment stays the ledger truth.", "operationId": "list_links_hospitality_cashier_transaction", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.cashier_transaction:read" ] } ], "summary": "List links of Cashier transaction", "tags": [ "cashiering" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.cashier_transaction_in_session", "hospitality.link.cashier_transaction_mirrors_payment" ] } } ] }, "/v1/object-types/hospitality.cashier_transaction/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne typed cash movement in a cashier session — cash_in, cash_out, tip_out, expense (OPERA's paid-out), or float_adjustment. Amounts are non-negative; the kind carries the direction. Append-only: corrections are compensating entries, never edits. Optionally mirrors a folio payment through cashier_transaction_mirrors_payment — the drawer entry is the mirror, the payment stays the ledger truth.", "operationId": "traverse_hospitality_cashier_transaction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.cashier_transaction_in_session", "hospitality.link.cashier_transaction_mirrors_payment" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.cashier_transaction:read" ] } ], "summary": "Traverse from Cashier transaction", "tags": [ "cashiering" ] } }, "/v1/object-types/hospitality.cashier_transaction/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne typed cash movement in a cashier session — cash_in, cash_out, tip_out, expense (OPERA's paid-out), or float_adjustment. Amounts are non-negative; the kind carries the direction. Append-only: corrections are compensating entries, never edits. Optionally mirrors a folio payment through cashier_transaction_mirrors_payment — the drawer entry is the mirror, the payment stays the ledger truth.", "operationId": "search_hospitality_cashier_transaction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "cash_in", "cash_out", "tip_out", "expense", "float_adjustment" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "occurred_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "occurred_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "occurred_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "kind", "occurred_at", "notes" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.cashier_transaction" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "Amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Cashier transaction amount", "type": "object" }, "id": { "title": "Cashier transaction id", "type": "string" }, "kind": { "enum": [ "cash_in", "cash_out", "tip_out", "expense", "float_adjustment" ], "title": "Movement kind", "type": "string" }, "notes": { "title": "Notes (the reason for the movement)", "type": "string" }, "occurred_at": { "format": "date-time", "title": "Occurred at", "type": "string" } }, "required": [ "id", "kind", "occurred_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.cashier_transaction:read" ] } ], "summary": "Search Cashier transaction", "tags": [ "cashiering" ] } }, "/v1/object-types/hospitality.channel/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA distribution channel: direct booking, an OTA, a GDS, a tour operator, etc. Channels carry their own credentials/state and are connected to rate plans they distribute via the `channel_distributes_rate_plan` link, replacing the prior single-channel enum on `RatePlan`.", "operationId": "get_hospitality_channel", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Channel code", "type": "string" }, "commission_flat_amount": { "description": "Per-booking flat commission", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Channel commission flat amount", "type": "object" }, "commission_kind": { "enum": [ "percent_of_revenue", "per_booking_flat", "per_booking_plus_percent", "none" ], "title": "Commission kind", "type": "string" }, "commission_rate": { "format": "decimal", "title": "Current commission rate", "type": "string" }, "external_code": { "title": "External / partner code", "type": "string" }, "kind": { "enum": [ "direct_web", "direct_call", "direct_walk_in", "ota", "gds", "wholesale", "tour_operator", "corporate", "metasearch", "social", "other" ], "title": "Channel kind", "type": "string" }, "name": { "title": "Channel name", "type": "string" }, "status": { "enum": [ "active", "paused", "closed" ], "title": "Status", "type": "string" }, "target_share": { "format": "decimal", "title": "Operational target share", "type": "string" }, "target_share_basis": { "enum": [ "bookings", "revenue", "room_nights" ], "title": "Target share basis", "type": "string" } }, "required": [ "code", "name", "kind", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel:read" ] } ], "summary": "Read Channel", "tags": [ "distribution" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.channel/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA distribution channel: direct booking, an OTA, a GDS, a tour operator, etc. Channels carry their own credentials/state and are connected to rate plans they distribute via the `channel_distributes_rate_plan` link, replacing the prior single-channel enum on `RatePlan`.", "operationId": "get_hospitality_channel_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.channel" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel:read" ] } ], "summary": "Read Channel as of a watermark", "tags": [ "distribution" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.channel/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA distribution channel: direct booking, an OTA, a GDS, a tour operator, etc. Channels carry their own credentials/state and are connected to rate plans they distribute via the `channel_distributes_rate_plan` link, replacing the prior single-channel enum on `RatePlan`.", "operationId": "list_links_hospitality_channel", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel:read" ] } ], "summary": "List links of Channel", "tags": [ "distribution" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.channel_commission_period_for_channel", "hospitality.link.channel_connection_carries_channel", "hospitality.link.channel_distributes_rate_plan", "hospitality.link.channel_for_property", "hospitality.link.commission_detail_owed_to_channel", "hospitality.link.reservation_delivery_from_channel", "hospitality.link.reservation_via_channel" ] } } ] }, "/v1/object-types/hospitality.channel/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA distribution channel: direct booking, an OTA, a GDS, a tour operator, etc. Channels carry their own credentials/state and are connected to rate plans they distribute via the `channel_distributes_rate_plan` link, replacing the prior single-channel enum on `RatePlan`.", "operationId": "traverse_hospitality_channel", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.channel_commission_period_for_channel", "hospitality.link.channel_connection_carries_channel", "hospitality.link.channel_distributes_rate_plan", "hospitality.link.channel_for_property", "hospitality.link.commission_detail_owed_to_channel", "hospitality.link.reservation_delivery_from_channel", "hospitality.link.reservation_via_channel" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel:read" ] } ], "summary": "Traverse from Channel", "tags": [ "distribution" ] } }, "/v1/object-types/hospitality.channel/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA distribution channel: direct booking, an OTA, a GDS, a tour operator, etc. Channels carry their own credentials/state and are connected to rate plans they distribute via the `channel_distributes_rate_plan` link, replacing the prior single-channel enum on `RatePlan`.", "operationId": "search_hospitality_channel", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "direct_web", "direct_call", "direct_walk_in", "ota", "gds", "wholesale", "tour_operator", "corporate", "metasearch", "social", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "paused", "closed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commission_rate" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commission_rate" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commission_rate" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commission_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "percent_of_revenue", "per_booking_flat", "per_booking_plus_percent", "none" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commission_flat_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_share" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_share" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_share" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_share_basis" }, "type": { "const": "eq" }, "value": { "enum": [ "bookings", "revenue", "room_nights" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "kind", "external_code", "status", "commission_rate", "commission_kind", "target_share", "target_share_basis" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Channel code", "type": "string" }, "commission_flat_amount": { "description": "Per-booking flat commission", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Channel commission flat amount", "type": "object" }, "commission_kind": { "enum": [ "percent_of_revenue", "per_booking_flat", "per_booking_plus_percent", "none" ], "title": "Commission kind", "type": "string" }, "commission_rate": { "format": "decimal", "title": "Current commission rate", "type": "string" }, "external_code": { "title": "External / partner code", "type": "string" }, "kind": { "enum": [ "direct_web", "direct_call", "direct_walk_in", "ota", "gds", "wholesale", "tour_operator", "corporate", "metasearch", "social", "other" ], "title": "Channel kind", "type": "string" }, "name": { "title": "Channel name", "type": "string" }, "status": { "enum": [ "active", "paused", "closed" ], "title": "Status", "type": "string" }, "target_share": { "format": "decimal", "title": "Operational target share", "type": "string" }, "target_share_basis": { "enum": [ "bookings", "revenue", "room_nights" ], "title": "Target share basis", "type": "string" } }, "required": [ "code", "name", "kind", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel:read" ] } ], "summary": "Search Channel", "tags": [ "distribution" ] } }, "/v1/object-types/hospitality.channel_commission_period/objects/{id}": { "get": { "description": "Read an existing instance.\n\nTime-varying commission contract for a (channel, property) pair. Carries the rate, kind, and flat-amount in effect for the period. Authoritative ledger over the `current` surface on `channel`; the channel scalar is the convenient operator- facing handle for the present row.", "operationId": "get_hospitality_channel_commission_period", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_commission_period" }, "properties": { "additionalProperties": false, "properties": { "commission_flat_amount": { "description": "Flat per-booking commission (flat kinds)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Channel commission period commission flat amount", "type": "object" }, "commission_kind": { "enum": [ "percent_of_revenue", "per_booking_flat", "per_booking_plus_percent", "none" ], "title": "Commission kind", "type": "string" }, "commission_kind_notes": { "title": "Operator-facing qualifier", "type": "string" }, "commission_rate": { "format": "decimal", "title": "Commission rate (percent kinds)", "type": "string" }, "effective_from": { "format": "date", "title": "Effective from", "type": "string" }, "effective_to": { "format": "date", "title": "Effective to (null = currently in effect)", "type": "string" }, "id": { "title": "Period id", "type": "string" } }, "required": [ "id", "effective_from" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_commission_period:read" ] } ], "summary": "Read Channel commission period", "tags": [ "distribution" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.channel_commission_period/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nTime-varying commission contract for a (channel, property) pair. Carries the rate, kind, and flat-amount in effect for the period. Authoritative ledger over the `current` surface on `channel`; the channel scalar is the convenient operator- facing handle for the present row.", "operationId": "get_hospitality_channel_commission_period_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.channel_commission_period" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_commission_period:read" ] } ], "summary": "Read Channel commission period as of a watermark", "tags": [ "distribution" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.channel_commission_period/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nTime-varying commission contract for a (channel, property) pair. Carries the rate, kind, and flat-amount in effect for the period. Authoritative ledger over the `current` surface on `channel`; the channel scalar is the convenient operator- facing handle for the present row.", "operationId": "list_links_hospitality_channel_commission_period", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_commission_period:read" ] } ], "summary": "List links of Channel commission period", "tags": [ "distribution" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.channel_commission_period_for_channel", "hospitality.link.channel_commission_period_for_property" ] } } ] }, "/v1/object-types/hospitality.channel_commission_period/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nTime-varying commission contract for a (channel, property) pair. Carries the rate, kind, and flat-amount in effect for the period. Authoritative ledger over the `current` surface on `channel`; the channel scalar is the convenient operator- facing handle for the present row.", "operationId": "traverse_hospitality_channel_commission_period", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.channel_commission_period_for_channel", "hospitality.link.channel_commission_period_for_property" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_commission_period:read" ] } ], "summary": "Traverse from Channel commission period", "tags": [ "distribution" ] } }, "/v1/object-types/hospitality.channel_commission_period/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nTime-varying commission contract for a (channel, property) pair. Carries the rate, kind, and flat-amount in effect for the period. Authoritative ledger over the `current` surface on `channel`; the channel scalar is the convenient operator- facing handle for the present row.", "operationId": "search_hospitality_channel_commission_period", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commission_rate" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commission_rate" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commission_rate" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commission_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "percent_of_revenue", "per_booking_flat", "per_booking_plus_percent", "none" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commission_flat_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commission_kind_notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commission_kind_notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "effective_from", "effective_to", "commission_rate", "commission_kind", "commission_kind_notes" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_commission_period" }, "properties": { "additionalProperties": false, "properties": { "commission_flat_amount": { "description": "Flat per-booking commission (flat kinds)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Channel commission period commission flat amount", "type": "object" }, "commission_kind": { "enum": [ "percent_of_revenue", "per_booking_flat", "per_booking_plus_percent", "none" ], "title": "Commission kind", "type": "string" }, "commission_kind_notes": { "title": "Operator-facing qualifier", "type": "string" }, "commission_rate": { "format": "decimal", "title": "Commission rate (percent kinds)", "type": "string" }, "effective_from": { "format": "date", "title": "Effective from", "type": "string" }, "effective_to": { "format": "date", "title": "Effective to (null = currently in effect)", "type": "string" }, "id": { "title": "Period id", "type": "string" } }, "required": [ "id", "effective_from" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_commission_period:read" ] } ], "summary": "Search Channel commission period", "tags": [ "distribution" ] } }, "/v1/object-types/hospitality.channel_connection/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne conduit between a property and a distribution partner — a channel manager, an OTA switch, or a partner that subscribed to our ARI. Identity, wire dialect and lifecycle only: credentials live in the secret store (`secret_ref` is a name, never a value), the per-date publication outbox lives in Postgres, and the demand channels the conduit carries are linked, not inlined. A conduit is not a channel — one connection fronts Booking.com, Expedia and dozens more, each of which stays its own `channel` row with its own commission period.", "operationId": "get_hospitality_channel_connection", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" }, "properties": { "additionalProperties": false, "properties": { "ari_endpoint_url": { "title": "HTTPS endpoint we publish ARI into", "type": "string" }, "display_name": { "title": "Human-readable name shown in the Explorer", "type": "string" }, "horizon_days": { "title": "Days forward from today that ARI is published for", "type": "integer" }, "id": { "title": "Connection id", "type": "string" }, "last_full_publication_at": { "format": "date-time", "title": "When a full (non-delta) publication last ran — gates the next one", "type": "string" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "owner_client_ref": { "title": "Client that registered this subscription (subscription provisioning only)", "type": "string" }, "partner_code": { "title": "The partner's identifier for our system (SiteMinder RequestorID / pmsCode)", "type": "string" }, "paused_reason": { "title": "Why publication is stopped (required while status = paused or suspended)", "type": "string" }, "price_basis": { "enum": [ "gross", "net", "gross_and_net" ], "title": "Whether published amounts are gross, net, or both", "type": "string" }, "property_code": { "title": "The partner's identifier for this property (SiteMinder HotelCode)", "type": "string" }, "protocol": { "enum": [ "pmsx_ota_2003_05", "mews_chm_v1", "aerandil_ari_v1", "other" ], "title": "Wire dialect this conduit speaks", "type": "string" }, "provider": { "title": "Partner identifier (siteminder / d_edge / derbysoft / …)", "type": "string" }, "provisioning": { "enum": [ "partner_hosted", "subscription" ], "title": "Who stood the conduit up (we call them, or they subscribed to us)", "type": "string" }, "rate_model": { "enum": [ "per_day", "occupancy_based" ], "title": "Published rate model — fixed per conduit, never per property", "type": "string" }, "registered_at": { "format": "date-time", "title": "When the connection was opened", "type": "string" }, "registered_by": { "title": "Principal::stable_id() of the registering principal", "type": "string" }, "reservation_delivery": { "enum": [ "partner_push", "we_pull", "none" ], "title": "How reservations reach us from the partner", "type": "string" }, "secret_ref": { "title": "Name of the credential in the external secret store (never the value)", "type": "string" }, "status": { "enum": [ "pending_mapping", "active", "paused", "suspended", "closed" ], "title": "Connection lifecycle status", "type": "string" } }, "required": [ "id", "display_name", "provider", "protocol", "provisioning", "status", "rate_model", "price_basis", "reservation_delivery", "horizon_days", "registered_by", "registered_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_connection:read" ] } ], "summary": "Read Channel connection", "tags": [ "channel_manager" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.channel_connection/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne conduit between a property and a distribution partner — a channel manager, an OTA switch, or a partner that subscribed to our ARI. Identity, wire dialect and lifecycle only: credentials live in the secret store (`secret_ref` is a name, never a value), the per-date publication outbox lives in Postgres, and the demand channels the conduit carries are linked, not inlined. A conduit is not a channel — one connection fronts Booking.com, Expedia and dozens more, each of which stays its own `channel` row with its own commission period.", "operationId": "get_hospitality_channel_connection_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_connection:read" ] } ], "summary": "Read Channel connection as of a watermark", "tags": [ "channel_manager" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.channel_connection/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne conduit between a property and a distribution partner — a channel manager, an OTA switch, or a partner that subscribed to our ARI. Identity, wire dialect and lifecycle only: credentials live in the secret store (`secret_ref` is a name, never a value), the per-date publication outbox lives in Postgres, and the demand channels the conduit carries are linked, not inlined. A conduit is not a channel — one connection fronts Booking.com, Expedia and dozens more, each of which stays its own `channel` row with its own commission period.", "operationId": "list_links_hospitality_channel_connection", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_connection:read" ] } ], "summary": "List links of Channel connection", "tags": [ "channel_manager" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.channel_connection_carries_channel", "hospitality.link.channel_connection_for_property", "hospitality.link.channel_mapping_for_connection", "hospitality.link.publication_run_for_connection", "hospitality.link.reservation_delivery_for_connection" ] } } ] }, "/v1/object-types/hospitality.channel_connection/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne conduit between a property and a distribution partner — a channel manager, an OTA switch, or a partner that subscribed to our ARI. Identity, wire dialect and lifecycle only: credentials live in the secret store (`secret_ref` is a name, never a value), the per-date publication outbox lives in Postgres, and the demand channels the conduit carries are linked, not inlined. A conduit is not a channel — one connection fronts Booking.com, Expedia and dozens more, each of which stays its own `channel` row with its own commission period.", "operationId": "traverse_hospitality_channel_connection", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.channel_connection_carries_channel", "hospitality.link.channel_connection_for_property", "hospitality.link.channel_mapping_for_connection", "hospitality.link.publication_run_for_connection", "hospitality.link.reservation_delivery_for_connection" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_connection:read" ] } ], "summary": "Traverse from Channel connection", "tags": [ "channel_manager" ] } }, "/v1/object-types/hospitality.channel_connection/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne conduit between a property and a distribution partner — a channel manager, an OTA switch, or a partner that subscribed to our ARI. Identity, wire dialect and lifecycle only: credentials live in the secret store (`secret_ref` is a name, never a value), the per-date publication outbox lives in Postgres, and the demand channels the conduit carries are linked, not inlined. A conduit is not a channel — one connection fronts Booking.com, Expedia and dozens more, each of which stays its own `channel` row with its own commission period.", "operationId": "search_hospitality_channel_connection", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "protocol" }, "type": { "const": "eq" }, "value": { "enum": [ "pmsx_ota_2003_05", "mews_chm_v1", "aerandil_ari_v1", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provisioning" }, "type": { "const": "eq" }, "value": { "enum": [ "partner_hosted", "subscription" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "pending_mapping", "active", "paused", "suspended", "closed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ari_endpoint_url" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ari_endpoint_url" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ari_endpoint_url" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ari_endpoint_url" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "secret_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "secret_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "secret_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "secret_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "partner_code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "partner_code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "partner_code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "partner_code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "property_code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "property_code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "property_code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "property_code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "owner_client_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "owner_client_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "owner_client_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "owner_client_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rate_model" }, "type": { "const": "eq" }, "value": { "enum": [ "per_day", "occupancy_based" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "price_basis" }, "type": { "const": "eq" }, "value": { "enum": [ "gross", "net", "gross_and_net" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reservation_delivery" }, "type": { "const": "eq" }, "value": { "enum": [ "partner_push", "we_pull", "none" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "horizon_days" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "horizon_days" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "horizon_days" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_full_publication_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_full_publication_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_full_publication_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "paused_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "paused_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "registered_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "registered_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "registered_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "registered_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "registered_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "registered_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "registered_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "display_name", "provider", "protocol", "provisioning", "status", "ari_endpoint_url", "secret_ref", "partner_code", "property_code", "owner_client_ref", "rate_model", "price_basis", "reservation_delivery", "horizon_days", "last_full_publication_at", "paused_reason", "registered_by", "registered_at", "notes" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_connection" }, "properties": { "additionalProperties": false, "properties": { "ari_endpoint_url": { "title": "HTTPS endpoint we publish ARI into", "type": "string" }, "display_name": { "title": "Human-readable name shown in the Explorer", "type": "string" }, "horizon_days": { "title": "Days forward from today that ARI is published for", "type": "integer" }, "id": { "title": "Connection id", "type": "string" }, "last_full_publication_at": { "format": "date-time", "title": "When a full (non-delta) publication last ran — gates the next one", "type": "string" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "owner_client_ref": { "title": "Client that registered this subscription (subscription provisioning only)", "type": "string" }, "partner_code": { "title": "The partner's identifier for our system (SiteMinder RequestorID / pmsCode)", "type": "string" }, "paused_reason": { "title": "Why publication is stopped (required while status = paused or suspended)", "type": "string" }, "price_basis": { "enum": [ "gross", "net", "gross_and_net" ], "title": "Whether published amounts are gross, net, or both", "type": "string" }, "property_code": { "title": "The partner's identifier for this property (SiteMinder HotelCode)", "type": "string" }, "protocol": { "enum": [ "pmsx_ota_2003_05", "mews_chm_v1", "aerandil_ari_v1", "other" ], "title": "Wire dialect this conduit speaks", "type": "string" }, "provider": { "title": "Partner identifier (siteminder / d_edge / derbysoft / …)", "type": "string" }, "provisioning": { "enum": [ "partner_hosted", "subscription" ], "title": "Who stood the conduit up (we call them, or they subscribed to us)", "type": "string" }, "rate_model": { "enum": [ "per_day", "occupancy_based" ], "title": "Published rate model — fixed per conduit, never per property", "type": "string" }, "registered_at": { "format": "date-time", "title": "When the connection was opened", "type": "string" }, "registered_by": { "title": "Principal::stable_id() of the registering principal", "type": "string" }, "reservation_delivery": { "enum": [ "partner_push", "we_pull", "none" ], "title": "How reservations reach us from the partner", "type": "string" }, "secret_ref": { "title": "Name of the credential in the external secret store (never the value)", "type": "string" }, "status": { "enum": [ "pending_mapping", "active", "paused", "suspended", "closed" ], "title": "Connection lifecycle status", "type": "string" } }, "required": [ "id", "display_name", "provider", "protocol", "provisioning", "status", "rate_model", "price_basis", "reservation_delivery", "horizon_days", "registered_by", "registered_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_connection:read" ] } ], "summary": "Search Channel connection", "tags": [ "channel_manager" ] } }, "/v1/object-types/hospitality.channel_mapping/objects/{id}": { "get": { "description": "Read an existing instance.\n\nBinds one of our room types or rate plans to the code a partner knows it by. Codes are per-connection — the same room type is `DBL` to one partner and `RT-004` to the next — and nothing can be published or accepted under a code with no mapping row. That refusal is not defensive programming: 'unmapped space code' and 'unmapped rate code' are named, required tests in the Mews certification suite, and an unmapped code is the single most common cause of a booking that never reaches the PMS.", "operationId": "get_hospitality_channel_mapping", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_mapping" }, "properties": { "additionalProperties": false, "properties": { "effective_from": { "format": "date", "title": "First date this binding applies", "type": "string" }, "effective_to": { "format": "date", "title": "Last date this binding applies (null = currently in effect)", "type": "string" }, "external_code": { "title": "The partner's code for this room type / rate plan", "type": "string" }, "external_name": { "title": "The partner's display name for it (drift check against their config)", "type": "string" }, "id": { "title": "Mapping id", "type": "string" }, "included_occupancy": { "title": "Adult occupancy the partner's price is quoted for (occupancy-based pricing)", "type": "integer" }, "mapping_kind": { "enum": [ "room_type", "rate_plan", "room_rate", "age_category", "extra" ], "title": "What this row binds", "type": "string" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "publish_rates": { "title": "Publish rate amounts for this binding", "type": "boolean" }, "publish_restrictions": { "title": "Publish restrictions for this binding", "type": "boolean" } }, "required": [ "id", "mapping_kind", "external_code", "publish_rates", "publish_restrictions", "effective_from" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_mapping:read" ] } ], "summary": "Read Channel mapping", "tags": [ "channel_manager" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.channel_mapping/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nBinds one of our room types or rate plans to the code a partner knows it by. Codes are per-connection — the same room type is `DBL` to one partner and `RT-004` to the next — and nothing can be published or accepted under a code with no mapping row. That refusal is not defensive programming: 'unmapped space code' and 'unmapped rate code' are named, required tests in the Mews certification suite, and an unmapped code is the single most common cause of a booking that never reaches the PMS.", "operationId": "get_hospitality_channel_mapping_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.channel_mapping" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_mapping:read" ] } ], "summary": "Read Channel mapping as of a watermark", "tags": [ "channel_manager" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.channel_mapping/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nBinds one of our room types or rate plans to the code a partner knows it by. Codes are per-connection — the same room type is `DBL` to one partner and `RT-004` to the next — and nothing can be published or accepted under a code with no mapping row. That refusal is not defensive programming: 'unmapped space code' and 'unmapped rate code' are named, required tests in the Mews certification suite, and an unmapped code is the single most common cause of a booking that never reaches the PMS.", "operationId": "list_links_hospitality_channel_mapping", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_mapping:read" ] } ], "summary": "List links of Channel mapping", "tags": [ "channel_manager" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.channel_mapping_for_connection", "hospitality.link.channel_mapping_for_rate_plan", "hospitality.link.channel_mapping_for_room_type" ] } } ] }, "/v1/object-types/hospitality.channel_mapping/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nBinds one of our room types or rate plans to the code a partner knows it by. Codes are per-connection — the same room type is `DBL` to one partner and `RT-004` to the next — and nothing can be published or accepted under a code with no mapping row. That refusal is not defensive programming: 'unmapped space code' and 'unmapped rate code' are named, required tests in the Mews certification suite, and an unmapped code is the single most common cause of a booking that never reaches the PMS.", "operationId": "traverse_hospitality_channel_mapping", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.channel_mapping_for_connection", "hospitality.link.channel_mapping_for_rate_plan", "hospitality.link.channel_mapping_for_room_type" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_mapping:read" ] } ], "summary": "Traverse from Channel mapping", "tags": [ "channel_manager" ] } }, "/v1/object-types/hospitality.channel_mapping/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nBinds one of our room types or rate plans to the code a partner knows it by. Codes are per-connection — the same room type is `DBL` to one partner and `RT-004` to the next — and nothing can be published or accepted under a code with no mapping row. That refusal is not defensive programming: 'unmapped space code' and 'unmapped rate code' are named, required tests in the Mews certification suite, and an unmapped code is the single most common cause of a booking that never reaches the PMS.", "operationId": "search_hospitality_channel_mapping", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "mapping_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "room_type", "rate_plan", "room_rate", "age_category", "extra" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "included_occupancy" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "included_occupancy" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "included_occupancy" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "publish_rates" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "publish_restrictions" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "mapping_kind", "external_code", "external_name", "included_occupancy", "effective_from", "effective_to", "notes" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_mapping" }, "properties": { "additionalProperties": false, "properties": { "effective_from": { "format": "date", "title": "First date this binding applies", "type": "string" }, "effective_to": { "format": "date", "title": "Last date this binding applies (null = currently in effect)", "type": "string" }, "external_code": { "title": "The partner's code for this room type / rate plan", "type": "string" }, "external_name": { "title": "The partner's display name for it (drift check against their config)", "type": "string" }, "id": { "title": "Mapping id", "type": "string" }, "included_occupancy": { "title": "Adult occupancy the partner's price is quoted for (occupancy-based pricing)", "type": "integer" }, "mapping_kind": { "enum": [ "room_type", "rate_plan", "room_rate", "age_category", "extra" ], "title": "What this row binds", "type": "string" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "publish_rates": { "title": "Publish rate amounts for this binding", "type": "boolean" }, "publish_restrictions": { "title": "Publish restrictions for this binding", "type": "boolean" } }, "required": [ "id", "mapping_kind", "external_code", "publish_rates", "publish_restrictions", "effective_from" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_mapping:read" ] } ], "summary": "Search Channel mapping", "tags": [ "channel_manager" ] } }, "/v1/object-types/hospitality.channel_mix_snapshot/objects/{id}": { "get": { "description": "Read an existing instance.\n\nDaily-materialised projection of bookings, room-nights, and revenue per channel for a property. Mirrors `night_audit_run` semantics: immutable post-write, one row per (property, business_date, cadence). Re-materialisation creates a new row, never a mutation. Operators that need to correct a snapshot delete the prior row first; the delete is itself an event so the correction is auditable.", "operationId": "get_hospitality_channel_mix_snapshot", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_mix_snapshot" }, "properties": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" }, "cadence": { "enum": [ "daily", "weekly", "monthly" ], "title": "Cadence", "type": "string" }, "direct_share_observed": { "format": "decimal", "title": "Direct share (decimal)", "type": "string" }, "gds_share_observed": { "format": "decimal", "title": "GDS share (decimal)", "type": "string" }, "id": { "title": "Snapshot id", "type": "string" }, "materialised_at": { "format": "date-time", "title": "When the snapshot was materialised (UTC)", "type": "string" }, "ota_share_observed": { "format": "decimal", "title": "OTA share (decimal)", "type": "string" }, "per_channel": { "description": "Per-channel contributions", "items": { "properties": { "bookings": { "type": "integer" }, "cancellations": { "type": "integer" }, "channel_code": { "type": "string" }, "channel_kind": { "type": "string" }, "commissions": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "gross_room_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "net_room_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "room_nights": { "type": "integer" }, "total_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "channel_code", "channel_kind", "bookings", "room_nights", "gross_room_revenue", "net_room_revenue", "total_revenue", "commissions", "cancellations" ], "type": "object" }, "title": "Channel mix snapshot per channel", "type": "array" } }, "required": [ "id", "business_date", "cadence", "materialised_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_mix_snapshot:read" ] } ], "summary": "Read Channel mix snapshot", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.channel_mix_snapshot/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nDaily-materialised projection of bookings, room-nights, and revenue per channel for a property. Mirrors `night_audit_run` semantics: immutable post-write, one row per (property, business_date, cadence). Re-materialisation creates a new row, never a mutation. Operators that need to correct a snapshot delete the prior row first; the delete is itself an event so the correction is auditable.", "operationId": "get_hospitality_channel_mix_snapshot_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.channel_mix_snapshot" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_mix_snapshot:read" ] } ], "summary": "Read Channel mix snapshot as of a watermark", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.channel_mix_snapshot/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nDaily-materialised projection of bookings, room-nights, and revenue per channel for a property. Mirrors `night_audit_run` semantics: immutable post-write, one row per (property, business_date, cadence). Re-materialisation creates a new row, never a mutation. Operators that need to correct a snapshot delete the prior row first; the delete is itself an event so the correction is auditable.", "operationId": "list_links_hospitality_channel_mix_snapshot", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_mix_snapshot:read" ] } ], "summary": "List links of Channel mix snapshot", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.property_has_channel_mix_snapshot" ] } } ] }, "/v1/object-types/hospitality.channel_mix_snapshot/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nDaily-materialised projection of bookings, room-nights, and revenue per channel for a property. Mirrors `night_audit_run` semantics: immutable post-write, one row per (property, business_date, cadence). Re-materialisation creates a new row, never a mutation. Operators that need to correct a snapshot delete the prior row first; the delete is itself an event so the correction is auditable.", "operationId": "traverse_hospitality_channel_mix_snapshot", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.property_has_channel_mix_snapshot" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_mix_snapshot:read" ] } ], "summary": "Traverse from Channel mix snapshot", "tags": [ "revenue" ] } }, "/v1/object-types/hospitality.channel_mix_snapshot/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nDaily-materialised projection of bookings, room-nights, and revenue per channel for a property. Mirrors `night_audit_run` semantics: immutable post-write, one row per (property, business_date, cadence). Re-materialisation creates a new row, never a mutation. Operators that need to correct a snapshot delete the prior row first; the delete is itself an event so the correction is auditable.", "operationId": "search_hospitality_channel_mix_snapshot", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cadence" }, "type": { "const": "eq" }, "value": { "enum": [ "daily", "weekly", "monthly" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "per_channel" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "bookings": { "type": "integer" }, "cancellations": { "type": "integer" }, "channel_code": { "type": "string" }, "channel_kind": { "type": "string" }, "commissions": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "gross_room_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "net_room_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "room_nights": { "type": "integer" }, "total_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "channel_code", "channel_kind", "bookings", "room_nights", "gross_room_revenue", "net_room_revenue", "total_revenue", "commissions", "cancellations" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "direct_share_observed" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "direct_share_observed" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "direct_share_observed" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ota_share_observed" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ota_share_observed" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ota_share_observed" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "gds_share_observed" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "gds_share_observed" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "gds_share_observed" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "materialised_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "materialised_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "materialised_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "business_date", "cadence", "direct_share_observed", "ota_share_observed", "gds_share_observed", "materialised_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_mix_snapshot" }, "properties": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" }, "cadence": { "enum": [ "daily", "weekly", "monthly" ], "title": "Cadence", "type": "string" }, "direct_share_observed": { "format": "decimal", "title": "Direct share (decimal)", "type": "string" }, "gds_share_observed": { "format": "decimal", "title": "GDS share (decimal)", "type": "string" }, "id": { "title": "Snapshot id", "type": "string" }, "materialised_at": { "format": "date-time", "title": "When the snapshot was materialised (UTC)", "type": "string" }, "ota_share_observed": { "format": "decimal", "title": "OTA share (decimal)", "type": "string" }, "per_channel": { "description": "Per-channel contributions", "items": { "properties": { "bookings": { "type": "integer" }, "cancellations": { "type": "integer" }, "channel_code": { "type": "string" }, "channel_kind": { "type": "string" }, "commissions": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "gross_room_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "net_room_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "room_nights": { "type": "integer" }, "total_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "channel_code", "channel_kind", "bookings", "room_nights", "gross_room_revenue", "net_room_revenue", "total_revenue", "commissions", "cancellations" ], "type": "object" }, "title": "Channel mix snapshot per channel", "type": "array" } }, "required": [ "id", "business_date", "cadence", "materialised_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_mix_snapshot:read" ] } ], "summary": "Search Channel mix snapshot", "tags": [ "revenue" ] } }, "/v1/object-types/hospitality.channel_publication_run/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne audited ARI push at a conduit: what triggered it, when it ran, how many date-cells it published across availability, rates and restrictions, and how many the partner refused. Run-grain only — per-cell state stays in the publication outbox in Postgres. `partial` is a first-class outcome: a run that published four hundred cells and had eleven refused for an unmapped rate plan neither succeeded nor failed, and flattening it to either loses the only signal that mapping is broken.", "operationId": "get_hospitality_channel_publication_run", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_publication_run" }, "properties": { "additionalProperties": false, "properties": { "cells_published": { "title": "Date-cells successfully published across all facets", "type": "integer" }, "cells_rejected": { "title": "Date-cells the partner refused", "type": "integer" }, "error_summary": { "title": "Why the run failed or was partial (required for those outcomes)", "type": "string" }, "finished_at": { "format": "date-time", "title": "When the run reached a terminal status", "type": "string" }, "id": { "title": "Publication run id", "type": "string" }, "messages_sent": { "title": "Wire messages sent (bundling collapses many cells into one)", "type": "integer" }, "started_at": { "format": "date-time", "title": "When the run started", "type": "string" }, "status": { "enum": [ "running", "succeeded", "partial", "failed", "cancelled" ], "title": "Publication-run lifecycle status", "type": "string" }, "trigger": { "enum": [ "delta", "full", "recovery", "manual" ], "title": "What initiated this run", "type": "string" }, "window_end": { "format": "date", "title": "Last business date covered by this run", "type": "string" }, "window_start": { "format": "date", "title": "First business date covered by this run", "type": "string" } }, "required": [ "id", "status", "trigger", "started_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_publication_run:read" ] } ], "summary": "Read Channel publication run", "tags": [ "channel_manager" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.channel_publication_run/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne audited ARI push at a conduit: what triggered it, when it ran, how many date-cells it published across availability, rates and restrictions, and how many the partner refused. Run-grain only — per-cell state stays in the publication outbox in Postgres. `partial` is a first-class outcome: a run that published four hundred cells and had eleven refused for an unmapped rate plan neither succeeded nor failed, and flattening it to either loses the only signal that mapping is broken.", "operationId": "get_hospitality_channel_publication_run_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.channel_publication_run" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_publication_run:read" ] } ], "summary": "Read Channel publication run as of a watermark", "tags": [ "channel_manager" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.channel_publication_run/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne audited ARI push at a conduit: what triggered it, when it ran, how many date-cells it published across availability, rates and restrictions, and how many the partner refused. Run-grain only — per-cell state stays in the publication outbox in Postgres. `partial` is a first-class outcome: a run that published four hundred cells and had eleven refused for an unmapped rate plan neither succeeded nor failed, and flattening it to either loses the only signal that mapping is broken.", "operationId": "list_links_hospitality_channel_publication_run", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_publication_run:read" ] } ], "summary": "List links of Channel publication run", "tags": [ "channel_manager" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.publication_run_for_connection" ] } } ] }, "/v1/object-types/hospitality.channel_publication_run/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne audited ARI push at a conduit: what triggered it, when it ran, how many date-cells it published across availability, rates and restrictions, and how many the partner refused. Run-grain only — per-cell state stays in the publication outbox in Postgres. `partial` is a first-class outcome: a run that published four hundred cells and had eleven refused for an unmapped rate plan neither succeeded nor failed, and flattening it to either loses the only signal that mapping is broken.", "operationId": "traverse_hospitality_channel_publication_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.publication_run_for_connection" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_publication_run:read" ] } ], "summary": "Traverse from Channel publication run", "tags": [ "channel_manager" ] } }, "/v1/object-types/hospitality.channel_publication_run/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne audited ARI push at a conduit: what triggered it, when it ran, how many date-cells it published across availability, rates and restrictions, and how many the partner refused. Run-grain only — per-cell state stays in the publication outbox in Postgres. `partial` is a first-class outcome: a run that published four hundred cells and had eleven refused for an unmapped rate plan neither succeeded nor failed, and flattening it to either loses the only signal that mapping is broken.", "operationId": "search_hospitality_channel_publication_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "running", "succeeded", "partial", "failed", "cancelled" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "trigger" }, "type": { "const": "eq" }, "value": { "enum": [ "delta", "full", "recovery", "manual" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "finished_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "finished_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "finished_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "window_start" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "window_start" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "window_start" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "window_end" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "window_end" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "window_end" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cells_published" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cells_published" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cells_published" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cells_rejected" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cells_rejected" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cells_rejected" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "messages_sent" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "messages_sent" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "messages_sent" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "error_summary" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "error_summary" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "status", "trigger", "started_at", "finished_at", "window_start", "window_end", "cells_published", "cells_rejected", "messages_sent", "error_summary" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_publication_run" }, "properties": { "additionalProperties": false, "properties": { "cells_published": { "title": "Date-cells successfully published across all facets", "type": "integer" }, "cells_rejected": { "title": "Date-cells the partner refused", "type": "integer" }, "error_summary": { "title": "Why the run failed or was partial (required for those outcomes)", "type": "string" }, "finished_at": { "format": "date-time", "title": "When the run reached a terminal status", "type": "string" }, "id": { "title": "Publication run id", "type": "string" }, "messages_sent": { "title": "Wire messages sent (bundling collapses many cells into one)", "type": "integer" }, "started_at": { "format": "date-time", "title": "When the run started", "type": "string" }, "status": { "enum": [ "running", "succeeded", "partial", "failed", "cancelled" ], "title": "Publication-run lifecycle status", "type": "string" }, "trigger": { "enum": [ "delta", "full", "recovery", "manual" ], "title": "What initiated this run", "type": "string" }, "window_end": { "format": "date", "title": "Last business date covered by this run", "type": "string" }, "window_start": { "format": "date", "title": "First business date covered by this run", "type": "string" } }, "required": [ "id", "status", "trigger", "started_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_publication_run:read" ] } ], "summary": "Search Channel publication run", "tags": [ "channel_manager" ] } }, "/v1/object-types/hospitality.channel_reservation_delivery/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne inbound reservation message from a partner, with its de-duplication and acknowledgement state. Every channel wire is at-least-once — SiteMinder re-pushes every minute for ten attempts then every five, Booking.com re-serves anything unacknowledged inside its pickup window — so duplicate delivery is the norm and `external_message_id` is the key that makes a replay a no-op. The message is a report of a sale that already completed on the partner's side, not a request: where inventory is short, this row records the oversell rather than refusing the booking.", "operationId": "get_hospitality_channel_reservation_delivery", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_reservation_delivery" }, "properties": { "additionalProperties": false, "properties": { "acknowledged_at": { "format": "date-time", "title": "When our acknowledgement was sent to the partner", "type": "string" }, "applied_at": { "format": "date-time", "title": "When the message landed in the ontology", "type": "string" }, "connection_ref": { "title": "Business id of the conduit this arrived on (scopes the de-duplication key)", "type": "string" }, "external_message_id": { "title": "The partner's identifier for this message (de-duplication key)", "type": "string" }, "external_reservation_id": { "title": "The partner's identifier for the reservation (stable across book/modify/cancel)", "type": "string" }, "id": { "title": "Delivery id", "type": "string" }, "intent": { "enum": [ "book", "modify", "cancel" ], "title": "What the message asks of us", "type": "string" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "origin_channel_code": { "title": "The partner's code for the demand channel that sold the booking", "type": "string" }, "oversold_by": { "title": "Rooms the property went over its selling ceiling to accept this booking", "type": "integer" }, "payload_digest": { "title": "Digest of the verbatim partner payload held in raw staging", "type": "string" }, "received_at": { "format": "date-time", "title": "When the message reached us", "type": "string" }, "rejection_detail": { "title": "Operator-facing detail behind the rejection", "type": "string" }, "rejection_kind": { "enum": [ "unmapped_room_type", "unmapped_rate_plan", "unknown_property", "connection_inactive", "invalid_stay_dates", "malformed_payload", "business_rule", "other" ], "title": "Why the message was permanently refused (state = rejected)", "type": "string" }, "status": { "enum": [ "received", "applied", "rejected", "failed" ], "title": "Delivery lifecycle state", "type": "string" } }, "required": [ "id", "connection_ref", "external_message_id", "external_reservation_id", "intent", "status", "received_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_reservation_delivery:read" ] } ], "summary": "Read Channel reservation delivery", "tags": [ "channel_manager" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.channel_reservation_delivery/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne inbound reservation message from a partner, with its de-duplication and acknowledgement state. Every channel wire is at-least-once — SiteMinder re-pushes every minute for ten attempts then every five, Booking.com re-serves anything unacknowledged inside its pickup window — so duplicate delivery is the norm and `external_message_id` is the key that makes a replay a no-op. The message is a report of a sale that already completed on the partner's side, not a request: where inventory is short, this row records the oversell rather than refusing the booking.", "operationId": "get_hospitality_channel_reservation_delivery_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.channel_reservation_delivery" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_reservation_delivery:read" ] } ], "summary": "Read Channel reservation delivery as of a watermark", "tags": [ "channel_manager" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.channel_reservation_delivery/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne inbound reservation message from a partner, with its de-duplication and acknowledgement state. Every channel wire is at-least-once — SiteMinder re-pushes every minute for ten attempts then every five, Booking.com re-serves anything unacknowledged inside its pickup window — so duplicate delivery is the norm and `external_message_id` is the key that makes a replay a no-op. The message is a report of a sale that already completed on the partner's side, not a request: where inventory is short, this row records the oversell rather than refusing the booking.", "operationId": "list_links_hospitality_channel_reservation_delivery", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_reservation_delivery:read" ] } ], "summary": "List links of Channel reservation delivery", "tags": [ "channel_manager" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.reservation_delivery_for_connection", "hospitality.link.reservation_delivery_from_channel", "hospitality.link.reservation_delivery_produced_reservation" ] } } ] }, "/v1/object-types/hospitality.channel_reservation_delivery/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne inbound reservation message from a partner, with its de-duplication and acknowledgement state. Every channel wire is at-least-once — SiteMinder re-pushes every minute for ten attempts then every five, Booking.com re-serves anything unacknowledged inside its pickup window — so duplicate delivery is the norm and `external_message_id` is the key that makes a replay a no-op. The message is a report of a sale that already completed on the partner's side, not a request: where inventory is short, this row records the oversell rather than refusing the booking.", "operationId": "traverse_hospitality_channel_reservation_delivery", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.reservation_delivery_for_connection", "hospitality.link.reservation_delivery_from_channel", "hospitality.link.reservation_delivery_produced_reservation" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_reservation_delivery:read" ] } ], "summary": "Traverse from Channel reservation delivery", "tags": [ "channel_manager" ] } }, "/v1/object-types/hospitality.channel_reservation_delivery/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne inbound reservation message from a partner, with its de-duplication and acknowledgement state. Every channel wire is at-least-once — SiteMinder re-pushes every minute for ten attempts then every five, Booking.com re-serves anything unacknowledged inside its pickup window — so duplicate delivery is the norm and `external_message_id` is the key that makes a replay a no-op. The message is a report of a sale that already completed on the partner's side, not a request: where inventory is short, this row records the oversell rather than refusing the booking.", "operationId": "search_hospitality_channel_reservation_delivery", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "connection_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "connection_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "connection_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "connection_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_message_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_message_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_message_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_message_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_reservation_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_reservation_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_reservation_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_reservation_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "intent" }, "type": { "const": "eq" }, "value": { "enum": [ "book", "modify", "cancel" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "received", "applied", "rejected", "failed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "received_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "received_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "received_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "acknowledged_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "acknowledged_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "acknowledged_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "origin_channel_code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "origin_channel_code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "origin_channel_code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "origin_channel_code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payload_digest" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payload_digest" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payload_digest" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payload_digest" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejection_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "unmapped_room_type", "unmapped_rate_plan", "unknown_property", "connection_inactive", "invalid_stay_dates", "malformed_payload", "business_rule", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejection_detail" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejection_detail" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "oversold_by" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "oversold_by" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "oversold_by" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "connection_ref", "external_message_id", "external_reservation_id", "intent", "status", "received_at", "applied_at", "acknowledged_at", "origin_channel_code", "payload_digest", "rejection_kind", "rejection_detail", "oversold_by", "notes" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.channel_reservation_delivery" }, "properties": { "additionalProperties": false, "properties": { "acknowledged_at": { "format": "date-time", "title": "When our acknowledgement was sent to the partner", "type": "string" }, "applied_at": { "format": "date-time", "title": "When the message landed in the ontology", "type": "string" }, "connection_ref": { "title": "Business id of the conduit this arrived on (scopes the de-duplication key)", "type": "string" }, "external_message_id": { "title": "The partner's identifier for this message (de-duplication key)", "type": "string" }, "external_reservation_id": { "title": "The partner's identifier for the reservation (stable across book/modify/cancel)", "type": "string" }, "id": { "title": "Delivery id", "type": "string" }, "intent": { "enum": [ "book", "modify", "cancel" ], "title": "What the message asks of us", "type": "string" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "origin_channel_code": { "title": "The partner's code for the demand channel that sold the booking", "type": "string" }, "oversold_by": { "title": "Rooms the property went over its selling ceiling to accept this booking", "type": "integer" }, "payload_digest": { "title": "Digest of the verbatim partner payload held in raw staging", "type": "string" }, "received_at": { "format": "date-time", "title": "When the message reached us", "type": "string" }, "rejection_detail": { "title": "Operator-facing detail behind the rejection", "type": "string" }, "rejection_kind": { "enum": [ "unmapped_room_type", "unmapped_rate_plan", "unknown_property", "connection_inactive", "invalid_stay_dates", "malformed_payload", "business_rule", "other" ], "title": "Why the message was permanently refused (state = rejected)", "type": "string" }, "status": { "enum": [ "received", "applied", "rejected", "failed" ], "title": "Delivery lifecycle state", "type": "string" } }, "required": [ "id", "connection_ref", "external_message_id", "external_reservation_id", "intent", "status", "received_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.channel_reservation_delivery:read" ] } ], "summary": "Search Channel reservation delivery", "tags": [ "channel_manager" ] } }, "/v1/object-types/hospitality.charge/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA line item posted to a folio. Carries a USALI 12 `bucket` (the operated department revenue rolls up to) plus either a `charge_for_service_item` link (when posted against the service catalog) or a `system_charge_kind` enum (when the charge is system-generated — a room night, tax line, service charge, gratuity, adjustment, package discount).", "operationId": "get_hospitality_charge", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.charge" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "Amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Charge amount", "type": "object" }, "bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "USALI 12 department", "type": "string" }, "description": { "title": "Description", "type": "string" }, "device_ref": { "format": "uuid", "title": "The device a key-card tap was made at (set by `post_charge_by_credential`)", "type": "string", "x-aerandil-references": "hospitality.device" }, "external_ref": { "title": "Source-system key for connector-landed charges", "type": "string" }, "gratuity": { "description": "Gratuity", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Charge gratuity", "type": "object" }, "id": { "title": "Charge id", "type": "string" }, "outlet_id": { "format": "uuid", "title": "USALI 12 operated department (Schedule 3 or 4) the charge rolls up to. A synthetic `miscellaneous_income`-bucket outlet per property covers genuinely non-department revenue (interest, cancellation fees, lost-key charges).", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "package_attribution_kind": { "enum": [ "component_full_price", "component_allocated_price", "package_discount_adjustment" ], "title": "Package-attribution kind", "type": "string" }, "posted_at": { "format": "date-time", "title": "Posted at", "type": "string" }, "revenue_category": { "description": "What an F&B posting sold (food / soft drinks / alcohol / other), for a charge a room-charged check posted — one per category on the check. Absent on every other charge.", "enum": [ "food", "non_alcoholic_beverage", "alcoholic_beverage", "other" ], "title": "F&B revenue category", "type": "string" }, "signed_by": { "description": "The guest who signed for a posting made at an outlet — the guest the server confirmed on the booking's bill — so the bill says who signed. Set by a room-charged F&B payment that named its guest; absent otherwise.", "format": "uuid", "title": "The guest who signed for it", "type": "string", "x-aerandil-references": "hospitality.person" }, "system_charge_kind": { "enum": [ "room_night", "day_use", "tax", "service_charge", "gratuity", "adjustment", "package_discount", "forfeited_deposit", "no_show_fee", "cancellation_fee", "no_show_revenue" ], "title": "System-generated charge kind", "type": "string" }, "tax": { "description": "Tax", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Charge tax", "type": "object" }, "transferred_from_folio_id": { "format": "uuid", "title": "Folio this charge was transferred from, when it did not originate on the folio it currently sits on.", "type": "string", "x-aerandil-references": "hospitality.folio" }, "voided": { "title": "Voided", "type": "boolean" } }, "required": [ "id", "description", "amount", "tax", "gratuity", "posted_at", "bucket", "outlet_id", "voided" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.charge:read" ] } ], "summary": "Read Charge", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.charge/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA line item posted to a folio. Carries a USALI 12 `bucket` (the operated department revenue rolls up to) plus either a `charge_for_service_item` link (when posted against the service catalog) or a `system_charge_kind` enum (when the charge is system-generated — a room night, tax line, service charge, gratuity, adjustment, package discount).", "operationId": "get_hospitality_charge_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.charge" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.charge:read" ] } ], "summary": "Read Charge as of a watermark", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.charge/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA line item posted to a folio. Carries a USALI 12 `bucket` (the operated department revenue rolls up to) plus either a `charge_for_service_item` link (when posted against the service catalog) or a `system_charge_kind` enum (when the charge is system-generated — a room night, tax line, service charge, gratuity, adjustment, package discount).", "operationId": "list_links_hospitality_charge", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.charge:read" ] } ], "summary": "List links of Charge", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.banquet_order_line_posted_charge", "hospitality.link.charge_at_outlet", "hospitality.link.charge_attributed_to_package_component", "hospitality.link.charge_attributed_to_package_sale", "hospitality.link.charge_for_service_item", "hospitality.link.charge_for_stock_movement", "hospitality.link.charge_has_tax_application", "hospitality.link.charge_reverses_charge", "hospitality.link.charge_via_credential", "hospitality.link.check_payment_posted_charge", "hospitality.link.consumption_for_charge", "hospitality.link.folio_has_charge", "hospitality.link.fraud_assessment_for_charge", "hospitality.link.workflow_run_targets_charge" ] } } ] }, "/v1/object-types/hospitality.charge/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA line item posted to a folio. Carries a USALI 12 `bucket` (the operated department revenue rolls up to) plus either a `charge_for_service_item` link (when posted against the service catalog) or a `system_charge_kind` enum (when the charge is system-generated — a room night, tax line, service charge, gratuity, adjustment, package discount).", "operationId": "traverse_hospitality_charge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.banquet_order_line_posted_charge", "hospitality.link.charge_at_outlet", "hospitality.link.charge_attributed_to_package_component", "hospitality.link.charge_attributed_to_package_sale", "hospitality.link.charge_for_service_item", "hospitality.link.charge_for_stock_movement", "hospitality.link.charge_has_tax_application", "hospitality.link.charge_reverses_charge", "hospitality.link.charge_via_credential", "hospitality.link.check_payment_posted_charge", "hospitality.link.consumption_for_charge", "hospitality.link.folio_has_charge", "hospitality.link.fraud_assessment_for_charge", "hospitality.link.workflow_run_targets_charge" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.charge:read" ] } ], "summary": "Traverse from Charge", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.charge/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA line item posted to a folio. Carries a USALI 12 `bucket` (the operated department revenue rolls up to) plus either a `charge_for_service_item` link (when posted against the service catalog) or a `system_charge_kind` enum (when the charge is system-generated — a room night, tax line, service charge, gratuity, adjustment, package discount).", "operationId": "search_hospitality_charge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "gratuity" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "posted_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "posted_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "posted_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "bucket" }, "type": { "const": "eq" }, "value": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "system_charge_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "room_night", "day_use", "tax", "service_charge", "gratuity", "adjustment", "package_discount", "forfeited_deposit", "no_show_fee", "cancellation_fee", "no_show_revenue" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "outlet_id" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.outlet" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "transferred_from_folio_id" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.folio" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "package_attribution_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "component_full_price", "component_allocated_price", "package_discount_adjustment" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "voided" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revenue_category" }, "type": { "const": "eq" }, "value": { "enum": [ "food", "non_alcoholic_beverage", "alcoholic_beverage", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "signed_by" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.person" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "device_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.device" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "description", "posted_at", "bucket", "system_charge_kind", "package_attribution_kind", "external_ref", "revenue_category" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.charge" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "Amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Charge amount", "type": "object" }, "bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "USALI 12 department", "type": "string" }, "description": { "title": "Description", "type": "string" }, "device_ref": { "format": "uuid", "title": "The device a key-card tap was made at (set by `post_charge_by_credential`)", "type": "string", "x-aerandil-references": "hospitality.device" }, "external_ref": { "title": "Source-system key for connector-landed charges", "type": "string" }, "gratuity": { "description": "Gratuity", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Charge gratuity", "type": "object" }, "id": { "title": "Charge id", "type": "string" }, "outlet_id": { "format": "uuid", "title": "USALI 12 operated department (Schedule 3 or 4) the charge rolls up to. A synthetic `miscellaneous_income`-bucket outlet per property covers genuinely non-department revenue (interest, cancellation fees, lost-key charges).", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "package_attribution_kind": { "enum": [ "component_full_price", "component_allocated_price", "package_discount_adjustment" ], "title": "Package-attribution kind", "type": "string" }, "posted_at": { "format": "date-time", "title": "Posted at", "type": "string" }, "revenue_category": { "description": "What an F&B posting sold (food / soft drinks / alcohol / other), for a charge a room-charged check posted — one per category on the check. Absent on every other charge.", "enum": [ "food", "non_alcoholic_beverage", "alcoholic_beverage", "other" ], "title": "F&B revenue category", "type": "string" }, "signed_by": { "description": "The guest who signed for a posting made at an outlet — the guest the server confirmed on the booking's bill — so the bill says who signed. Set by a room-charged F&B payment that named its guest; absent otherwise.", "format": "uuid", "title": "The guest who signed for it", "type": "string", "x-aerandil-references": "hospitality.person" }, "system_charge_kind": { "enum": [ "room_night", "day_use", "tax", "service_charge", "gratuity", "adjustment", "package_discount", "forfeited_deposit", "no_show_fee", "cancellation_fee", "no_show_revenue" ], "title": "System-generated charge kind", "type": "string" }, "tax": { "description": "Tax", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Charge tax", "type": "object" }, "transferred_from_folio_id": { "format": "uuid", "title": "Folio this charge was transferred from, when it did not originate on the folio it currently sits on.", "type": "string", "x-aerandil-references": "hospitality.folio" }, "voided": { "title": "Voided", "type": "boolean" } }, "required": [ "id", "description", "amount", "tax", "gratuity", "posted_at", "bucket", "outlet_id", "voided" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.charge:read" ] } ], "summary": "Search Charge", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.check_line/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne ordered item on a guest check: menu item and variant, quantity, course, seat, unit price, revenue category and VAT snapshotted at order time, the kitchen's instructions, and the entered → fired → fulfilled lifecycle with the void/comp split: voided = removed BEFORE preparation (no COGS, no sale); comped = delivered but written off (product consumed — carries authority metadata). A modifier option that adds something sellable (add bacon) is a line of its own, linked to the line it modifies by check_line_modifies_line and priced and taxed as its own item; it follows its parent through fire, bump, void and comp and is never voided or comped alone.", "operationId": "get_hospitality_check_line", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.check_line" }, "properties": { "additionalProperties": false, "properties": { "comp_authorised_by": { "format": "uuid", "title": "Staff member who authorised the comp — the one signed in when it was comped", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "comp_escalation_required": { "title": "Comp exceeded the authoriser's per-incident limit", "type": "boolean" }, "comp_reason": { "title": "Why the line was comped (required when comped)", "type": "string" }, "course_number": { "title": "Course", "type": "integer" }, "external_ref": { "title": "Source-system key for replayed / connector-landed lines", "type": "string" }, "fired_at": { "format": "date-time", "title": "When the line fired to the kitchen", "type": "string" }, "fulfilled_at": { "format": "date-time", "title": "When the line's ticket bumped (or, for a connector-landed line, when service completed)", "type": "string" }, "id": { "title": "Line id", "type": "string" }, "instructions": { "description": "What the kitchen must do differently, in the order the modifiers were chosen: an option that adds nothing sellable (Medium rare), and a no / light / side prefix on any option (NO Onion, SIDE Dressing). Options that add something sellable are lines of their own.", "items": { "type": "string" }, "title": "Kitchen instructions", "type": "array" }, "modifier_prefix": { "description": "On a modifier line, the prefix its option was chosen with — `no` rings it free, `extra` another portion, `light` / `side` change how it is served. Absent on an item rung on its own, and on a modifier chosen plain.", "enum": [ "no", "extra", "light", "side" ], "title": "Prefix the modifier was chosen with (modifier lines only)", "type": "string" }, "notes": { "title": "Kitchen-facing note", "type": "string" }, "quantity": { "title": "Quantity", "type": "integer" }, "revenue_category": { "enum": [ "food", "non_alcoholic_beverage", "alcoholic_beverage", "other" ], "title": "Revenue category, from the item class at order time", "type": "string" }, "seat_number": { "description": "The seat the item is for, so the runner knows who gets which plate and a split by seat has its key. Absent = the table's (shared, or not taken).", "title": "Seat", "type": "integer" }, "status": { "enum": [ "entered", "fired", "fulfilled", "voided", "comped" ], "title": "Line lifecycle status", "type": "string" }, "tax_amount": { "description": "Total tax on quantity × unit price, each rule rounded to the penny half away from zero (never down — VAT Notice 700 §17.6). Inside the price when the rules are inclusive, on top when they add on.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Check line tax amount", "type": "object" }, "tax_class": { "title": "Tax class the line's VAT resolved through (eat-in or takeaway)", "type": "string" }, "tax_lines": { "description": "One entry per tax rule applied — code, jurisdiction, rate, amount, inclusive — the per-rate figures a VAT receipt totals. Empty only when no rule applied, which a sale never does.", "items": { "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "code": { "type": "string" }, "inclusive": { "type": "boolean" }, "jurisdiction": { "type": "string" }, "rate": { "format": "decimal", "type": "string" } }, "required": [ "code", "jurisdiction", "rate", "amount", "inclusive" ], "type": "object" }, "title": "Check line tax lines", "type": "array" }, "unit_price": { "description": "Unit price snapshotted from the variant's price in force at order time", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Check line unit price", "type": "object" }, "void_reason": { "enum": [ "guest_changed_mind", "entry_error", "item_unavailable", "long_wait", "duplicate", "other" ], "title": "Why the line was voided (required when voided)", "type": "string" } }, "required": [ "id", "status", "quantity", "course_number", "unit_price", "revenue_category", "tax_class", "tax_amount", "tax_lines" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.check_line:read" ] } ], "summary": "Read Check line", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.check_line/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne ordered item on a guest check: menu item and variant, quantity, course, seat, unit price, revenue category and VAT snapshotted at order time, the kitchen's instructions, and the entered → fired → fulfilled lifecycle with the void/comp split: voided = removed BEFORE preparation (no COGS, no sale); comped = delivered but written off (product consumed — carries authority metadata). A modifier option that adds something sellable (add bacon) is a line of its own, linked to the line it modifies by check_line_modifies_line and priced and taxed as its own item; it follows its parent through fire, bump, void and comp and is never voided or comped alone.", "operationId": "get_hospitality_check_line_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.check_line" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.check_line:read" ] } ], "summary": "Read Check line as of a watermark", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.check_line/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne ordered item on a guest check: menu item and variant, quantity, course, seat, unit price, revenue category and VAT snapshotted at order time, the kitchen's instructions, and the entered → fired → fulfilled lifecycle with the void/comp split: voided = removed BEFORE preparation (no COGS, no sale); comped = delivered but written off (product consumed — carries authority metadata). A modifier option that adds something sellable (add bacon) is a line of its own, linked to the line it modifies by check_line_modifies_line and priced and taxed as its own item; it follows its parent through fire, bump, void and comp and is never voided or comped alone.", "operationId": "list_links_hospitality_check_line", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.check_line:read" ] } ], "summary": "List links of Check line", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.check_line_for_menu_item", "hospitality.link.check_line_for_variant", "hospitality.link.check_line_modifies_line", "hospitality.link.check_line_on_check", "hospitality.link.check_line_on_ticket" ] } } ] }, "/v1/object-types/hospitality.check_line/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne ordered item on a guest check: menu item and variant, quantity, course, seat, unit price, revenue category and VAT snapshotted at order time, the kitchen's instructions, and the entered → fired → fulfilled lifecycle with the void/comp split: voided = removed BEFORE preparation (no COGS, no sale); comped = delivered but written off (product consumed — carries authority metadata). A modifier option that adds something sellable (add bacon) is a line of its own, linked to the line it modifies by check_line_modifies_line and priced and taxed as its own item; it follows its parent through fire, bump, void and comp and is never voided or comped alone.", "operationId": "traverse_hospitality_check_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.check_line_for_menu_item", "hospitality.link.check_line_for_variant", "hospitality.link.check_line_modifies_line", "hospitality.link.check_line_on_check", "hospitality.link.check_line_on_ticket" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.check_line:read" ] } ], "summary": "Traverse from Check line", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.check_line/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne ordered item on a guest check: menu item and variant, quantity, course, seat, unit price, revenue category and VAT snapshotted at order time, the kitchen's instructions, and the entered → fired → fulfilled lifecycle with the void/comp split: voided = removed BEFORE preparation (no COGS, no sale); comped = delivered but written off (product consumed — carries authority metadata). A modifier option that adds something sellable (add bacon) is a line of its own, linked to the line it modifies by check_line_modifies_line and priced and taxed as its own item; it follows its parent through fire, bump, void and comp and is never voided or comped alone.", "operationId": "search_hospitality_check_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "entered", "fired", "fulfilled", "voided", "comped" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quantity" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quantity" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quantity" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "course_number" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "course_number" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "course_number" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "seat_number" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "seat_number" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "seat_number" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "unit_price" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revenue_category" }, "type": { "const": "eq" }, "value": { "enum": [ "food", "non_alcoholic_beverage", "alcoholic_beverage", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_class" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_class" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_class" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_class" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_lines" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "code": { "type": "string" }, "inclusive": { "type": "boolean" }, "jurisdiction": { "type": "string" }, "rate": { "format": "decimal", "type": "string" } }, "required": [ "code", "jurisdiction", "rate", "amount", "inclusive" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "modifier_prefix" }, "type": { "const": "eq" }, "value": { "enum": [ "no", "extra", "light", "side" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "instructions" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "void_reason" }, "type": { "const": "eq" }, "value": { "enum": [ "guest_changed_mind", "entry_error", "item_unavailable", "long_wait", "duplicate", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "comp_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "comp_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "comp_authorised_by" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "comp_escalation_required" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fired_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fired_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fired_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fulfilled_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fulfilled_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fulfilled_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "status", "quantity", "course_number", "seat_number", "revenue_category", "tax_class", "modifier_prefix", "notes", "void_reason", "comp_reason", "fired_at", "fulfilled_at", "external_ref" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.check_line" }, "properties": { "additionalProperties": false, "properties": { "comp_authorised_by": { "format": "uuid", "title": "Staff member who authorised the comp — the one signed in when it was comped", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "comp_escalation_required": { "title": "Comp exceeded the authoriser's per-incident limit", "type": "boolean" }, "comp_reason": { "title": "Why the line was comped (required when comped)", "type": "string" }, "course_number": { "title": "Course", "type": "integer" }, "external_ref": { "title": "Source-system key for replayed / connector-landed lines", "type": "string" }, "fired_at": { "format": "date-time", "title": "When the line fired to the kitchen", "type": "string" }, "fulfilled_at": { "format": "date-time", "title": "When the line's ticket bumped (or, for a connector-landed line, when service completed)", "type": "string" }, "id": { "title": "Line id", "type": "string" }, "instructions": { "description": "What the kitchen must do differently, in the order the modifiers were chosen: an option that adds nothing sellable (Medium rare), and a no / light / side prefix on any option (NO Onion, SIDE Dressing). Options that add something sellable are lines of their own.", "items": { "type": "string" }, "title": "Kitchen instructions", "type": "array" }, "modifier_prefix": { "description": "On a modifier line, the prefix its option was chosen with — `no` rings it free, `extra` another portion, `light` / `side` change how it is served. Absent on an item rung on its own, and on a modifier chosen plain.", "enum": [ "no", "extra", "light", "side" ], "title": "Prefix the modifier was chosen with (modifier lines only)", "type": "string" }, "notes": { "title": "Kitchen-facing note", "type": "string" }, "quantity": { "title": "Quantity", "type": "integer" }, "revenue_category": { "enum": [ "food", "non_alcoholic_beverage", "alcoholic_beverage", "other" ], "title": "Revenue category, from the item class at order time", "type": "string" }, "seat_number": { "description": "The seat the item is for, so the runner knows who gets which plate and a split by seat has its key. Absent = the table's (shared, or not taken).", "title": "Seat", "type": "integer" }, "status": { "enum": [ "entered", "fired", "fulfilled", "voided", "comped" ], "title": "Line lifecycle status", "type": "string" }, "tax_amount": { "description": "Total tax on quantity × unit price, each rule rounded to the penny half away from zero (never down — VAT Notice 700 §17.6). Inside the price when the rules are inclusive, on top when they add on.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Check line tax amount", "type": "object" }, "tax_class": { "title": "Tax class the line's VAT resolved through (eat-in or takeaway)", "type": "string" }, "tax_lines": { "description": "One entry per tax rule applied — code, jurisdiction, rate, amount, inclusive — the per-rate figures a VAT receipt totals. Empty only when no rule applied, which a sale never does.", "items": { "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "code": { "type": "string" }, "inclusive": { "type": "boolean" }, "jurisdiction": { "type": "string" }, "rate": { "format": "decimal", "type": "string" } }, "required": [ "code", "jurisdiction", "rate", "amount", "inclusive" ], "type": "object" }, "title": "Check line tax lines", "type": "array" }, "unit_price": { "description": "Unit price snapshotted from the variant's price in force at order time", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Check line unit price", "type": "object" }, "void_reason": { "enum": [ "guest_changed_mind", "entry_error", "item_unavailable", "long_wait", "duplicate", "other" ], "title": "Why the line was voided (required when voided)", "type": "string" } }, "required": [ "id", "status", "quantity", "course_number", "unit_price", "revenue_category", "tax_class", "tax_amount", "tax_lines" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.check_line:read" ] } ], "summary": "Search Check line", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.check_payment/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne tender taken against a guest check (check_payment_on_check) — the kernel is the system of record for a check's payments. `amount` is what it applied to the check, `tip` rides beside it and stays out of what was paid; cash may be `tendered` above the balance and gives `change_given`. A card payment carries the terminal's references (`psp_reference`, `terminal_transaction_id`, `poiid`), never card data. A room charge or charge-to-key posts to its folio (check_payment_to_folio) one charge per revenue category and the tip as a gratuity charge (check_payment_posted_charge). `allocation` records the payment's share of each revenue category and its VAT, so a check paid in parts sums exactly. Written only by add_check_payment / settle_check.", "operationId": "get_hospitality_check_payment", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.check_payment" }, "properties": { "additionalProperties": false, "properties": { "allocation": { "description": "Per revenue category, what of `amount` paid it and the tax inside that share, per rule — apportioned by largest remainder over what the earlier payments left, so a check's payments sum exactly to its categories and its VAT. A room charge posts these shares to the folio.", "items": { "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "revenue_category": { "enum": [ "food", "non_alcoholic_beverage", "alcoholic_beverage", "other" ], "type": "string" }, "tax": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "tax_lines": { "items": { "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "code": { "type": "string" }, "inclusive": { "type": "boolean" }, "jurisdiction": { "type": "string" }, "rate": { "format": "decimal", "type": "string" } }, "required": [ "code", "jurisdiction", "rate", "amount", "inclusive" ], "type": "object" }, "type": "array" } }, "required": [ "revenue_category", "amount", "tax", "tax_lines" ], "type": "object" }, "title": "Check payment allocation", "type": "array" }, "allowance_applied": { "description": "What of the payment the stay's package allowance covered — the food and soft-drink share, capped at what the day's allowance had left, never the tip. The folio carries that part as the package's balance-neutral consumption line and only the rest as charges the guest owes; the consumption row names this payment (`consumption_for_check_payment`). Absent when nothing was covered.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Check payment allowance applied", "type": "object" }, "amount": { "description": "Applied to the check (tip excluded)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Check payment amount", "type": "object" }, "authorised_by": { "format": "uuid", "title": "The manager whose say-so overrode the stay's posting rules — the staff member signed in when the payment was taken", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "change_given": { "description": "Change handed back (cash only)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Check payment change given", "type": "object" }, "external_ref": { "title": "Source-system key for replayed / connector-landed payments", "type": "string" }, "guest_id": { "description": "The guest the server confirmed for a room charge — the reservation's guest (a sharer signs on their own booking). Carried onto the folio charges as `signed_by`.", "format": "uuid", "title": "The guest who signed", "type": "string", "x-aerandil-references": "hospitality.person" }, "id": { "title": "Payment id", "type": "string" }, "override_kind": { "enum": [ "no_post", "no_credit" ], "title": "What a manager's override let through: the stay's no-post flag (no_post) or its credit (no_credit)", "type": "string" }, "override_reason": { "title": "Why the manager overrode the stay's posting rules", "type": "string" }, "paid_at": { "format": "date-time", "title": "When the payment was taken — business time", "type": "string" }, "poiid": { "title": "The terminal (point of interaction) the card was taken on", "type": "string" }, "psp_reference": { "title": "The processor's reference for the card payment (Adyen pspReference) — an identifier, not a credential", "type": "string" }, "recorded_by": { "title": "Principal::stable_id() of the principal that took the payment", "type": "string" }, "reservation_id": { "description": "The booking whose bill a room charge or charge-to-key posted to — the folio belongs to it (a stay's window or the booking's own account). OHIP posts to a reservation, never to a room.", "format": "uuid", "title": "The reservation a room charge posted to", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "staff_member_id": { "format": "uuid", "title": "The staff member who took the payment, when the session is one", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "tender": { "enum": [ "room_charge", "cash", "card", "comp", "external", "charge_to_key" ], "title": "Tender", "type": "string" }, "tendered": { "description": "Cash handed over (cash only)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Check payment tendered", "type": "object" }, "terminal_transaction_id": { "title": "The terminal's own transaction id for the card payment", "type": "string" }, "tip": { "description": "The tip taken with the payment — a pass-through to the staff under the Employment (Allocation of Tips) Act 2023, never revenue and never in `paid_total`. Zero when none.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Check payment tip", "type": "object" } }, "required": [ "id", "tender", "amount", "tip", "paid_at", "recorded_by", "allocation" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.check_payment:read" ] } ], "summary": "Read Check payment", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.check_payment/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne tender taken against a guest check (check_payment_on_check) — the kernel is the system of record for a check's payments. `amount` is what it applied to the check, `tip` rides beside it and stays out of what was paid; cash may be `tendered` above the balance and gives `change_given`. A card payment carries the terminal's references (`psp_reference`, `terminal_transaction_id`, `poiid`), never card data. A room charge or charge-to-key posts to its folio (check_payment_to_folio) one charge per revenue category and the tip as a gratuity charge (check_payment_posted_charge). `allocation` records the payment's share of each revenue category and its VAT, so a check paid in parts sums exactly. Written only by add_check_payment / settle_check.", "operationId": "get_hospitality_check_payment_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.check_payment" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.check_payment:read" ] } ], "summary": "Read Check payment as of a watermark", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.check_payment/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne tender taken against a guest check (check_payment_on_check) — the kernel is the system of record for a check's payments. `amount` is what it applied to the check, `tip` rides beside it and stays out of what was paid; cash may be `tendered` above the balance and gives `change_given`. A card payment carries the terminal's references (`psp_reference`, `terminal_transaction_id`, `poiid`), never card data. A room charge or charge-to-key posts to its folio (check_payment_to_folio) one charge per revenue category and the tip as a gratuity charge (check_payment_posted_charge). `allocation` records the payment's share of each revenue category and its VAT, so a check paid in parts sums exactly. Written only by add_check_payment / settle_check.", "operationId": "list_links_hospitality_check_payment", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.check_payment:read" ] } ], "summary": "List links of Check payment", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.check_payment_on_check", "hospitality.link.check_payment_posted_charge", "hospitality.link.check_payment_to_folio", "hospitality.link.consumption_for_check_payment" ] } } ] }, "/v1/object-types/hospitality.check_payment/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne tender taken against a guest check (check_payment_on_check) — the kernel is the system of record for a check's payments. `amount` is what it applied to the check, `tip` rides beside it and stays out of what was paid; cash may be `tendered` above the balance and gives `change_given`. A card payment carries the terminal's references (`psp_reference`, `terminal_transaction_id`, `poiid`), never card data. A room charge or charge-to-key posts to its folio (check_payment_to_folio) one charge per revenue category and the tip as a gratuity charge (check_payment_posted_charge). `allocation` records the payment's share of each revenue category and its VAT, so a check paid in parts sums exactly. Written only by add_check_payment / settle_check.", "operationId": "traverse_hospitality_check_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.check_payment_on_check", "hospitality.link.check_payment_posted_charge", "hospitality.link.check_payment_to_folio", "hospitality.link.consumption_for_check_payment" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.check_payment:read" ] } ], "summary": "Traverse from Check payment", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.check_payment/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne tender taken against a guest check (check_payment_on_check) — the kernel is the system of record for a check's payments. `amount` is what it applied to the check, `tip` rides beside it and stays out of what was paid; cash may be `tendered` above the balance and gives `change_given`. A card payment carries the terminal's references (`psp_reference`, `terminal_transaction_id`, `poiid`), never card data. A room charge or charge-to-key posts to its folio (check_payment_to_folio) one charge per revenue category and the tip as a gratuity charge (check_payment_posted_charge). `allocation` records the payment's share of each revenue category and its VAT, so a check paid in parts sums exactly. Written only by add_check_payment / settle_check.", "operationId": "search_hospitality_check_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tender" }, "type": { "const": "eq" }, "value": { "enum": [ "room_charge", "cash", "card", "comp", "external", "charge_to_key" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tip" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tendered" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "change_given" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "terminal_transaction_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "terminal_transaction_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "terminal_transaction_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "terminal_transaction_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "poiid" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "poiid" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "poiid" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "poiid" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "paid_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "paid_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "paid_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "staff_member_id" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reservation_id" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "guest_id" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.person" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "allocation" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "revenue_category": { "enum": [ "food", "non_alcoholic_beverage", "alcoholic_beverage", "other" ], "type": "string" }, "tax": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "tax_lines": { "items": { "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "code": { "type": "string" }, "inclusive": { "type": "boolean" }, "jurisdiction": { "type": "string" }, "rate": { "format": "decimal", "type": "string" } }, "required": [ "code", "jurisdiction", "rate", "amount", "inclusive" ], "type": "object" }, "type": "array" } }, "required": [ "revenue_category", "amount", "tax", "tax_lines" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "allowance_applied" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "override_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "no_post", "no_credit" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authorised_by" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "override_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "override_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "tender", "psp_reference", "terminal_transaction_id", "poiid", "paid_at", "recorded_by", "external_ref", "override_kind", "override_reason" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.check_payment" }, "properties": { "additionalProperties": false, "properties": { "allocation": { "description": "Per revenue category, what of `amount` paid it and the tax inside that share, per rule — apportioned by largest remainder over what the earlier payments left, so a check's payments sum exactly to its categories and its VAT. A room charge posts these shares to the folio.", "items": { "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "revenue_category": { "enum": [ "food", "non_alcoholic_beverage", "alcoholic_beverage", "other" ], "type": "string" }, "tax": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "tax_lines": { "items": { "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "code": { "type": "string" }, "inclusive": { "type": "boolean" }, "jurisdiction": { "type": "string" }, "rate": { "format": "decimal", "type": "string" } }, "required": [ "code", "jurisdiction", "rate", "amount", "inclusive" ], "type": "object" }, "type": "array" } }, "required": [ "revenue_category", "amount", "tax", "tax_lines" ], "type": "object" }, "title": "Check payment allocation", "type": "array" }, "allowance_applied": { "description": "What of the payment the stay's package allowance covered — the food and soft-drink share, capped at what the day's allowance had left, never the tip. The folio carries that part as the package's balance-neutral consumption line and only the rest as charges the guest owes; the consumption row names this payment (`consumption_for_check_payment`). Absent when nothing was covered.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Check payment allowance applied", "type": "object" }, "amount": { "description": "Applied to the check (tip excluded)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Check payment amount", "type": "object" }, "authorised_by": { "format": "uuid", "title": "The manager whose say-so overrode the stay's posting rules — the staff member signed in when the payment was taken", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "change_given": { "description": "Change handed back (cash only)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Check payment change given", "type": "object" }, "external_ref": { "title": "Source-system key for replayed / connector-landed payments", "type": "string" }, "guest_id": { "description": "The guest the server confirmed for a room charge — the reservation's guest (a sharer signs on their own booking). Carried onto the folio charges as `signed_by`.", "format": "uuid", "title": "The guest who signed", "type": "string", "x-aerandil-references": "hospitality.person" }, "id": { "title": "Payment id", "type": "string" }, "override_kind": { "enum": [ "no_post", "no_credit" ], "title": "What a manager's override let through: the stay's no-post flag (no_post) or its credit (no_credit)", "type": "string" }, "override_reason": { "title": "Why the manager overrode the stay's posting rules", "type": "string" }, "paid_at": { "format": "date-time", "title": "When the payment was taken — business time", "type": "string" }, "poiid": { "title": "The terminal (point of interaction) the card was taken on", "type": "string" }, "psp_reference": { "title": "The processor's reference for the card payment (Adyen pspReference) — an identifier, not a credential", "type": "string" }, "recorded_by": { "title": "Principal::stable_id() of the principal that took the payment", "type": "string" }, "reservation_id": { "description": "The booking whose bill a room charge or charge-to-key posted to — the folio belongs to it (a stay's window or the booking's own account). OHIP posts to a reservation, never to a room.", "format": "uuid", "title": "The reservation a room charge posted to", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "staff_member_id": { "format": "uuid", "title": "The staff member who took the payment, when the session is one", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "tender": { "enum": [ "room_charge", "cash", "card", "comp", "external", "charge_to_key" ], "title": "Tender", "type": "string" }, "tendered": { "description": "Cash handed over (cash only)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Check payment tendered", "type": "object" }, "terminal_transaction_id": { "title": "The terminal's own transaction id for the card payment", "type": "string" }, "tip": { "description": "The tip taken with the payment — a pass-through to the staff under the Employment (Allocation of Tips) Act 2023, never revenue and never in `paid_total`. Zero when none.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Check payment tip", "type": "object" } }, "required": [ "id", "tender", "amount", "tip", "paid_at", "recorded_by", "allocation" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.check_payment:read" ] } ], "summary": "Search Check payment", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.check_receipt/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe guest's receipt for a settled check — issued when the check's balance reaches zero, numbered from the outlet's receipt series (`R-{outlet}-{000001}`) and chained by hash onto the property's issued documents, invoices and credit notes included. A snapshot of what a UK simplified invoice needs (VAT Notice 700 §16.6.1: supplier name, address and VAT number, time of supply, what was supplied, per-rate VAT-inclusive totals and rates) plus the check number, outlet, server, business date, lines, tenders, tips and change. Not a VAT invoice: no recipient. A room charge prints as charged to the room, with the guest's name and no card detail. Never edited after issue.", "operationId": "get_hospitality_check_receipt", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.check_receipt" }, "properties": { "additionalProperties": false, "properties": { "business_date": { "description": "The check's business date — the hotel date it opened on.", "format": "date", "title": "Business date", "type": "string" }, "change_total": { "description": "Cash handed back across the payments.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Check receipt change total", "type": "object" }, "check_number": { "description": "The check's own number, the one the server says aloud.", "title": "Check number", "type": "string" }, "content_hash": { "description": "SHA-256 over the receipt's canonical fields (the invoice's field list: issuer tax reference, series, number, business date, kind `receipt`, tax, total) and `previous_hash`.", "title": "Content hash", "type": "string" }, "covers": { "title": "Covers", "type": "integer" }, "currency": { "format": "iso-4217", "title": "Currency", "type": "string" }, "issued_at": { "description": "The instant the receipt was issued.", "format": "date-time", "title": "Issued at", "type": "string" }, "issuer": { "description": "The supplier's legal identity as it printed — the property's legal name, address and VAT number from its billing identity; its own name and address under scheme `none` when it has no billing identity; absent when it has neither (a till never refuses a guest their slip over back-office configuration).", "properties": { "address": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "type": "object" }, "bank_account": { "properties": { "account_name": { "type": "string" }, "account_number": { "type": "string" }, "bic": { "type": "string" }, "iban": { "type": "string" }, "sort_code": { "type": "string" } }, "type": "object" }, "company_registration_number": { "type": "string" }, "contact_email": { "type": "string" }, "contact_phone": { "type": "string" }, "legal_name": { "type": "string" }, "tax_registration_number": { "type": "string" }, "tax_registration_scheme": { "type": "string" } }, "required": [ "legal_name", "address", "tax_registration_scheme" ], "title": "Check receipt issuer", "type": "object" }, "lines": { "description": "What was supplied, in the order it rang: each fulfilled or comped line with its modifier lines after it (`modifier: true`). Voided lines were never made and are not printed; a comped line prints at its price, marked.", "items": { "properties": { "comped": { "type": "boolean" }, "description": { "type": "string" }, "line_total": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "modifier": { "type": "boolean" }, "quantity": { "type": "integer" }, "unit_price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "description", "quantity", "unit_price", "line_total", "modifier", "comped" ], "type": "object" }, "title": "Check receipt lines", "type": "array" }, "number": { "description": "`R-{outlet code}-{000001}` — drawn from the outlet's dense receipt series inside the settling transaction and never reissued.", "title": "Receipt number", "type": "string" }, "order_kind": { "enum": [ "dine_in", "takeaway", "room_service", "delivery" ], "title": "How the order reached the guest", "type": "string" }, "outlet_name": { "title": "Outlet", "type": "string" }, "paid_total": { "description": "What the payments applied to the check, tips out.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Check receipt paid total", "type": "object" }, "payments": { "description": "Each tender in the order it was taken: amount, tip, cash tendered and change; a room charge with its room and the name of the guest who signed — never card data.", "items": { "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "change_given": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "guest_name": { "type": "string" }, "room_number": { "type": "string" }, "tender": { "enum": [ "room_charge", "cash", "card", "comp", "external", "charge_to_key" ], "type": "string" }, "tendered": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "tip": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "tender", "amount", "tip" ], "type": "object" }, "title": "Check receipt payments", "type": "array" }, "previous_hash": { "description": "The property's previous issued document's `content_hash` — invoice, credit note or receipt: one chain per property. Absent only on the property's first document.", "title": "Previous content hash", "type": "string" }, "sequence_value": { "description": "The bare counter value `number` was rendered from, so a gap is detectable without parsing the number.", "title": "Sequence value", "type": "integer" }, "series": { "description": "The sequence the number came from — `{property_id}:receipt:{outlet_id}`: one run per outlet (a till prints its own), dense, and kept apart from the property's invoice and credit-note runs.", "title": "Number series", "type": "string" }, "server_name": { "description": "The owning server's given name, as it printed.", "title": "Server", "type": "string" }, "settled_at": { "description": "When the check settled — the time of supply the receipt prints (Notice 700 §16.6.1).", "format": "date-time", "title": "Time of supply", "type": "string" }, "simplified": { "description": "Always true: a till receipt is the retailer's simplified invoice, issued without the customer's details.", "title": "Simplified", "type": "boolean" }, "subtotal": { "description": "The live lines' gross — comps and voids out, inclusive VAT in.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Check receipt subtotal", "type": "object" }, "supplier_name": { "description": "The house's name as the slip heads it.", "title": "Supplier", "type": "string" }, "table_label": { "title": "Table", "type": "string" }, "tax_total": { "description": "VAT", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Check receipt tax total", "type": "object" }, "time_of_supply": { "description": "`settled_at` in the house's own time zone, as the slip prints it (`2026-11-02 19:42`; ` UTC` appended when the property names no zone) — snapshotted so a render needs no clock and no zone database.", "title": "Time of supply, as printed", "type": "string" }, "tip_total": { "description": "Tips taken with the payments — outside the scope of VAT.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Check receipt tip total", "type": "object" }, "total_due": { "description": "What the guest owed: subtotal plus any add-on tax.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Check receipt total due", "type": "object" }, "vat": { "description": "Per tax rule and rate over the live lines: the code, the rate, and the net, tax and VAT-inclusive gross — the per-rate figures Notice 700 §16.6.1 asks a simplified invoice to show.", "items": { "properties": { "code": { "type": "string" }, "gross": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "net": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "rate": { "format": "decimal", "type": "string" }, "tax": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "code", "rate", "net", "tax", "gross" ], "type": "object" }, "title": "Check receipt vat", "type": "array" } }, "required": [ "number", "series", "sequence_value", "check_number", "outlet_name", "order_kind", "business_date", "settled_at", "time_of_supply", "issued_at", "currency", "subtotal", "tax_total", "total_due", "paid_total", "tip_total", "change_total", "vat", "lines", "supplier_name", "simplified", "content_hash" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.check_receipt:read" ] } ], "summary": "Read Check receipt", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.check_receipt/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe guest's receipt for a settled check — issued when the check's balance reaches zero, numbered from the outlet's receipt series (`R-{outlet}-{000001}`) and chained by hash onto the property's issued documents, invoices and credit notes included. A snapshot of what a UK simplified invoice needs (VAT Notice 700 §16.6.1: supplier name, address and VAT number, time of supply, what was supplied, per-rate VAT-inclusive totals and rates) plus the check number, outlet, server, business date, lines, tenders, tips and change. Not a VAT invoice: no recipient. A room charge prints as charged to the room, with the guest's name and no card detail. Never edited after issue.", "operationId": "get_hospitality_check_receipt_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.check_receipt" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.check_receipt:read" ] } ], "summary": "Read Check receipt as of a watermark", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.check_receipt/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe guest's receipt for a settled check — issued when the check's balance reaches zero, numbered from the outlet's receipt series (`R-{outlet}-{000001}`) and chained by hash onto the property's issued documents, invoices and credit notes included. A snapshot of what a UK simplified invoice needs (VAT Notice 700 §16.6.1: supplier name, address and VAT number, time of supply, what was supplied, per-rate VAT-inclusive totals and rates) plus the check number, outlet, server, business date, lines, tenders, tips and change. Not a VAT invoice: no recipient. A room charge prints as charged to the room, with the guest's name and no card detail. Never edited after issue.", "operationId": "list_links_hospitality_check_receipt", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.check_receipt:read" ] } ], "summary": "List links of Check receipt", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.receipt_for_check" ] } } ] }, "/v1/object-types/hospitality.check_receipt/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe guest's receipt for a settled check — issued when the check's balance reaches zero, numbered from the outlet's receipt series (`R-{outlet}-{000001}`) and chained by hash onto the property's issued documents, invoices and credit notes included. A snapshot of what a UK simplified invoice needs (VAT Notice 700 §16.6.1: supplier name, address and VAT number, time of supply, what was supplied, per-rate VAT-inclusive totals and rates) plus the check number, outlet, server, business date, lines, tenders, tips and change. Not a VAT invoice: no recipient. A room charge prints as charged to the room, with the guest's name and no card detail. Never edited after issue.", "operationId": "traverse_hospitality_check_receipt", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.receipt_for_check" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.check_receipt:read" ] } ], "summary": "Traverse from Check receipt", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.check_receipt/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe guest's receipt for a settled check — issued when the check's balance reaches zero, numbered from the outlet's receipt series (`R-{outlet}-{000001}`) and chained by hash onto the property's issued documents, invoices and credit notes included. A snapshot of what a UK simplified invoice needs (VAT Notice 700 §16.6.1: supplier name, address and VAT number, time of supply, what was supplied, per-rate VAT-inclusive totals and rates) plus the check number, outlet, server, business date, lines, tenders, tips and change. Not a VAT invoice: no recipient. A room charge prints as charged to the room, with the guest's name and no card detail. Never edited after issue.", "operationId": "search_hospitality_check_receipt", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "number" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "number" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "number" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "number" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "series" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "series" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "series" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "series" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sequence_value" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sequence_value" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sequence_value" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "check_number" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "check_number" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "check_number" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "check_number" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "outlet_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "outlet_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "outlet_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "outlet_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "order_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "dine_in", "takeaway", "room_service", "delivery" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "table_label" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "table_label" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "table_label" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "table_label" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "covers" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "covers" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "covers" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "server_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "server_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "server_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "server_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "settled_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "settled_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "settled_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "time_of_supply" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "time_of_supply" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "time_of_supply" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "time_of_supply" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "currency" }, "type": { "const": "eq" }, "value": { "format": "iso-4217", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "subtotal" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_total" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "total_due" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "paid_total" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tip_total" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "change_total" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vat" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "code": { "type": "string" }, "gross": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "net": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "rate": { "format": "decimal", "type": "string" }, "tax": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "code", "rate", "net", "tax", "gross" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "lines" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "comped": { "type": "boolean" }, "description": { "type": "string" }, "line_total": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "modifier": { "type": "boolean" }, "quantity": { "type": "integer" }, "unit_price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "description", "quantity", "unit_price", "line_total", "modifier", "comped" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payments" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "change_given": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "guest_name": { "type": "string" }, "room_number": { "type": "string" }, "tender": { "enum": [ "room_charge", "cash", "card", "comp", "external", "charge_to_key" ], "type": "string" }, "tendered": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "tip": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "tender", "amount", "tip" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "supplier_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "supplier_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "supplier_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "supplier_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issuer" }, "type": { "const": "eq" }, "value": { "properties": { "address": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "type": "object" }, "bank_account": { "properties": { "account_name": { "type": "string" }, "account_number": { "type": "string" }, "bic": { "type": "string" }, "iban": { "type": "string" }, "sort_code": { "type": "string" } }, "type": "object" }, "company_registration_number": { "type": "string" }, "contact_email": { "type": "string" }, "contact_phone": { "type": "string" }, "legal_name": { "type": "string" }, "tax_registration_number": { "type": "string" }, "tax_registration_scheme": { "type": "string" } }, "required": [ "legal_name", "address", "tax_registration_scheme" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "simplified" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "content_hash" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "content_hash" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "content_hash" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "content_hash" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "previous_hash" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "previous_hash" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "previous_hash" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "previous_hash" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "number", "series", "sequence_value", "check_number", "outlet_name", "order_kind", "table_label", "covers", "server_name", "business_date", "settled_at", "time_of_supply", "issued_at", "supplier_name", "content_hash", "previous_hash" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.check_receipt" }, "properties": { "additionalProperties": false, "properties": { "business_date": { "description": "The check's business date — the hotel date it opened on.", "format": "date", "title": "Business date", "type": "string" }, "change_total": { "description": "Cash handed back across the payments.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Check receipt change total", "type": "object" }, "check_number": { "description": "The check's own number, the one the server says aloud.", "title": "Check number", "type": "string" }, "content_hash": { "description": "SHA-256 over the receipt's canonical fields (the invoice's field list: issuer tax reference, series, number, business date, kind `receipt`, tax, total) and `previous_hash`.", "title": "Content hash", "type": "string" }, "covers": { "title": "Covers", "type": "integer" }, "currency": { "format": "iso-4217", "title": "Currency", "type": "string" }, "issued_at": { "description": "The instant the receipt was issued.", "format": "date-time", "title": "Issued at", "type": "string" }, "issuer": { "description": "The supplier's legal identity as it printed — the property's legal name, address and VAT number from its billing identity; its own name and address under scheme `none` when it has no billing identity; absent when it has neither (a till never refuses a guest their slip over back-office configuration).", "properties": { "address": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "type": "object" }, "bank_account": { "properties": { "account_name": { "type": "string" }, "account_number": { "type": "string" }, "bic": { "type": "string" }, "iban": { "type": "string" }, "sort_code": { "type": "string" } }, "type": "object" }, "company_registration_number": { "type": "string" }, "contact_email": { "type": "string" }, "contact_phone": { "type": "string" }, "legal_name": { "type": "string" }, "tax_registration_number": { "type": "string" }, "tax_registration_scheme": { "type": "string" } }, "required": [ "legal_name", "address", "tax_registration_scheme" ], "title": "Check receipt issuer", "type": "object" }, "lines": { "description": "What was supplied, in the order it rang: each fulfilled or comped line with its modifier lines after it (`modifier: true`). Voided lines were never made and are not printed; a comped line prints at its price, marked.", "items": { "properties": { "comped": { "type": "boolean" }, "description": { "type": "string" }, "line_total": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "modifier": { "type": "boolean" }, "quantity": { "type": "integer" }, "unit_price": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "description", "quantity", "unit_price", "line_total", "modifier", "comped" ], "type": "object" }, "title": "Check receipt lines", "type": "array" }, "number": { "description": "`R-{outlet code}-{000001}` — drawn from the outlet's dense receipt series inside the settling transaction and never reissued.", "title": "Receipt number", "type": "string" }, "order_kind": { "enum": [ "dine_in", "takeaway", "room_service", "delivery" ], "title": "How the order reached the guest", "type": "string" }, "outlet_name": { "title": "Outlet", "type": "string" }, "paid_total": { "description": "What the payments applied to the check, tips out.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Check receipt paid total", "type": "object" }, "payments": { "description": "Each tender in the order it was taken: amount, tip, cash tendered and change; a room charge with its room and the name of the guest who signed — never card data.", "items": { "properties": { "amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "change_given": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "guest_name": { "type": "string" }, "room_number": { "type": "string" }, "tender": { "enum": [ "room_charge", "cash", "card", "comp", "external", "charge_to_key" ], "type": "string" }, "tendered": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "tip": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "tender", "amount", "tip" ], "type": "object" }, "title": "Check receipt payments", "type": "array" }, "previous_hash": { "description": "The property's previous issued document's `content_hash` — invoice, credit note or receipt: one chain per property. Absent only on the property's first document.", "title": "Previous content hash", "type": "string" }, "sequence_value": { "description": "The bare counter value `number` was rendered from, so a gap is detectable without parsing the number.", "title": "Sequence value", "type": "integer" }, "series": { "description": "The sequence the number came from — `{property_id}:receipt:{outlet_id}`: one run per outlet (a till prints its own), dense, and kept apart from the property's invoice and credit-note runs.", "title": "Number series", "type": "string" }, "server_name": { "description": "The owning server's given name, as it printed.", "title": "Server", "type": "string" }, "settled_at": { "description": "When the check settled — the time of supply the receipt prints (Notice 700 §16.6.1).", "format": "date-time", "title": "Time of supply", "type": "string" }, "simplified": { "description": "Always true: a till receipt is the retailer's simplified invoice, issued without the customer's details.", "title": "Simplified", "type": "boolean" }, "subtotal": { "description": "The live lines' gross — comps and voids out, inclusive VAT in.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Check receipt subtotal", "type": "object" }, "supplier_name": { "description": "The house's name as the slip heads it.", "title": "Supplier", "type": "string" }, "table_label": { "title": "Table", "type": "string" }, "tax_total": { "description": "VAT", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Check receipt tax total", "type": "object" }, "time_of_supply": { "description": "`settled_at` in the house's own time zone, as the slip prints it (`2026-11-02 19:42`; ` UTC` appended when the property names no zone) — snapshotted so a render needs no clock and no zone database.", "title": "Time of supply, as printed", "type": "string" }, "tip_total": { "description": "Tips taken with the payments — outside the scope of VAT.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Check receipt tip total", "type": "object" }, "total_due": { "description": "What the guest owed: subtotal plus any add-on tax.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Check receipt total due", "type": "object" }, "vat": { "description": "Per tax rule and rate over the live lines: the code, the rate, and the net, tax and VAT-inclusive gross — the per-rate figures Notice 700 §16.6.1 asks a simplified invoice to show.", "items": { "properties": { "code": { "type": "string" }, "gross": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "net": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "rate": { "format": "decimal", "type": "string" }, "tax": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "code", "rate", "net", "tax", "gross" ], "type": "object" }, "title": "Check receipt vat", "type": "array" } }, "required": [ "number", "series", "sequence_value", "check_number", "outlet_name", "order_kind", "business_date", "settled_at", "time_of_supply", "issued_at", "currency", "subtotal", "tax_total", "total_due", "paid_total", "tip_total", "change_total", "vat", "lines", "supplier_name", "simplified", "content_hash" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.check_receipt:read" ] } ], "summary": "Search Check receipt", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.checklist_result/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne recording of a checklist template against one housekeeping task (`checklist_result_for_task`, `checklist_result_for_template`): the answered items, the recorder's remarks, who ticked it (`checklist_result_recorded_by`) and when. `score` is derived, never typed: the template's `check` items ticked ok ÷ all its `check` items, × 100, rounded half up — `checks_passed` and `checks_total` are its evidence; a template with no `check` items scores nothing. Photo items' pictures hang off the result as attachments (`stored_object_for_checklist_result`). One result per task × template: recording again replaces it in place while the task is open. A supervisor's inspection list is the same object recorded against the inspection task.", "operationId": "get_hospitality_checklist_result", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.checklist_result" }, "properties": { "additionalProperties": false, "properties": { "checks_passed": { "title": "How many of those were ticked ok", "type": "integer" }, "checks_total": { "title": "How many of the template's items are `check` items", "type": "integer" }, "id": { "title": "Checklist result id", "type": "string" }, "items": { "description": "The answered items, by template item code", "items": { "properties": { "code": { "type": "string" }, "ok": { "type": "boolean" }, "remark": { "type": "string" }, "value": { "type": "string" } }, "required": [ "code", "ok" ], "type": "object" }, "title": "Checklist result items", "type": "array" }, "recorded_at": { "format": "date-time", "title": "When the list was ticked (the handset's tap, when it says)", "type": "string" }, "remarks": { "title": "The recorder's remarks on the whole list", "type": "string" }, "score": { "title": "checks_passed ÷ checks_total × 100, rounded half up; absent when the template has no check items", "type": "integer" } }, "required": [ "id", "items", "checks_total", "checks_passed", "recorded_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.checklist_result:read" ] } ], "summary": "Read Checklist result", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.checklist_result/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne recording of a checklist template against one housekeeping task (`checklist_result_for_task`, `checklist_result_for_template`): the answered items, the recorder's remarks, who ticked it (`checklist_result_recorded_by`) and when. `score` is derived, never typed: the template's `check` items ticked ok ÷ all its `check` items, × 100, rounded half up — `checks_passed` and `checks_total` are its evidence; a template with no `check` items scores nothing. Photo items' pictures hang off the result as attachments (`stored_object_for_checklist_result`). One result per task × template: recording again replaces it in place while the task is open. A supervisor's inspection list is the same object recorded against the inspection task.", "operationId": "get_hospitality_checklist_result_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.checklist_result" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.checklist_result:read" ] } ], "summary": "Read Checklist result as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.checklist_result/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne recording of a checklist template against one housekeeping task (`checklist_result_for_task`, `checklist_result_for_template`): the answered items, the recorder's remarks, who ticked it (`checklist_result_recorded_by`) and when. `score` is derived, never typed: the template's `check` items ticked ok ÷ all its `check` items, × 100, rounded half up — `checks_passed` and `checks_total` are its evidence; a template with no `check` items scores nothing. Photo items' pictures hang off the result as attachments (`stored_object_for_checklist_result`). One result per task × template: recording again replaces it in place while the task is open. A supervisor's inspection list is the same object recorded against the inspection task.", "operationId": "list_links_hospitality_checklist_result", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.checklist_result:read" ] } ], "summary": "List links of Checklist result", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.checklist_result_for_task", "hospitality.link.checklist_result_for_template", "hospitality.link.checklist_result_recorded_by", "hospitality.link.stored_object_for_checklist_result" ] } } ] }, "/v1/object-types/hospitality.checklist_result/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne recording of a checklist template against one housekeeping task (`checklist_result_for_task`, `checklist_result_for_template`): the answered items, the recorder's remarks, who ticked it (`checklist_result_recorded_by`) and when. `score` is derived, never typed: the template's `check` items ticked ok ÷ all its `check` items, × 100, rounded half up — `checks_passed` and `checks_total` are its evidence; a template with no `check` items scores nothing. Photo items' pictures hang off the result as attachments (`stored_object_for_checklist_result`). One result per task × template: recording again replaces it in place while the task is open. A supervisor's inspection list is the same object recorded against the inspection task.", "operationId": "traverse_hospitality_checklist_result", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.checklist_result_for_task", "hospitality.link.checklist_result_for_template", "hospitality.link.checklist_result_recorded_by", "hospitality.link.stored_object_for_checklist_result" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.checklist_result:read" ] } ], "summary": "Traverse from Checklist result", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.checklist_result/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne recording of a checklist template against one housekeeping task (`checklist_result_for_task`, `checklist_result_for_template`): the answered items, the recorder's remarks, who ticked it (`checklist_result_recorded_by`) and when. `score` is derived, never typed: the template's `check` items ticked ok ÷ all its `check` items, × 100, rounded half up — `checks_passed` and `checks_total` are its evidence; a template with no `check` items scores nothing. Photo items' pictures hang off the result as attachments (`stored_object_for_checklist_result`). One result per task × template: recording again replaces it in place while the task is open. A supervisor's inspection list is the same object recorded against the inspection task.", "operationId": "search_hospitality_checklist_result", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "items" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "code": { "type": "string" }, "ok": { "type": "boolean" }, "remark": { "type": "string" }, "value": { "type": "string" } }, "required": [ "code", "ok" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "remarks" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "remarks" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checks_total" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checks_total" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checks_total" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checks_passed" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checks_passed" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checks_passed" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "score" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "score" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "score" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "remarks", "checks_total", "checks_passed", "score", "recorded_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.checklist_result" }, "properties": { "additionalProperties": false, "properties": { "checks_passed": { "title": "How many of those were ticked ok", "type": "integer" }, "checks_total": { "title": "How many of the template's items are `check` items", "type": "integer" }, "id": { "title": "Checklist result id", "type": "string" }, "items": { "description": "The answered items, by template item code", "items": { "properties": { "code": { "type": "string" }, "ok": { "type": "boolean" }, "remark": { "type": "string" }, "value": { "type": "string" } }, "required": [ "code", "ok" ], "type": "object" }, "title": "Checklist result items", "type": "array" }, "recorded_at": { "format": "date-time", "title": "When the list was ticked (the handset's tap, when it says)", "type": "string" }, "remarks": { "title": "The recorder's remarks on the whole list", "type": "string" }, "score": { "title": "checks_passed ÷ checks_total × 100, rounded half up; absent when the template has no check items", "type": "integer" } }, "required": [ "id", "items", "checks_total", "checks_passed", "recorded_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.checklist_result:read" ] } ], "summary": "Search Checklist result", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.checklist_template/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe list an attendant ticks — or a supervisor inspects against — for one housekeeping task type, optionally one room type (`checklist_template_for_room_type`). A brand standard (`checklist_template_at_brand`) or the house's own (`checklist_template_at_property`); a task resolves the most specific active template: the house's for its room type, the house's for every room, the brand's for its room type, the brand's for every room. `required_for_completion` makes `complete_housekeeping_task` refuse until a `checklist_result` for this template is recorded against the task — hubOS's 'checklist for inspection' building toggle, per list instead of per building. One active template per (scope, task type, room type): re-defining one revises its items in place. A public-area task type's list may name a kind of area instead (`applies_to_area_kind`, 2026-10-14): an area's task resolves the list for its kind before the list for every area, at the house and then the brand.", "operationId": "get_hospitality_checklist_template", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.checklist_template" }, "properties": { "additionalProperties": false, "properties": { "applies_to_area_kind": { "enum": [ "lobby", "corridor", "lift", "stairwell", "pool", "gym", "spa_area", "restaurant_floor", "toilets", "back_of_house", "exterior", "other" ], "title": "The kind of public area the list is for (on a public-area task type only); absent: every area, or a room's list", "type": "string" }, "applies_to_task_type": { "enum": [ "stayover", "departure", "vacant_pickup", "deep_clean", "turndown", "inspection", "public_area_clean", "public_area_inspection", "minibar", "laundry" ], "title": "The housekeeping task type the list is for", "type": "string" }, "id": { "title": "Checklist template id", "type": "string" }, "items": { "description": "The items, in the order the attendant meets them", "items": { "properties": { "code": { "type": "string" }, "kind": { "enum": [ "check", "photo", "count", "text" ], "type": "string" }, "label": { "type": "string" } }, "required": [ "code", "label", "kind" ], "type": "object" }, "title": "Checklist template items", "type": "array" }, "name": { "title": "What the list is called on the handset", "type": "string" }, "required_for_completion": { "title": "Whether the task cannot complete without a recorded result", "type": "boolean" }, "retired_at": { "format": "date-time", "title": "When the template was retired", "type": "string" }, "status": { "enum": [ "active", "retired" ], "title": "Active (resolves onto tasks) or retired", "type": "string" } }, "required": [ "id", "name", "applies_to_task_type", "items", "required_for_completion", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.checklist_template:read" ] } ], "summary": "Read Checklist template", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.checklist_template/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe list an attendant ticks — or a supervisor inspects against — for one housekeeping task type, optionally one room type (`checklist_template_for_room_type`). A brand standard (`checklist_template_at_brand`) or the house's own (`checklist_template_at_property`); a task resolves the most specific active template: the house's for its room type, the house's for every room, the brand's for its room type, the brand's for every room. `required_for_completion` makes `complete_housekeeping_task` refuse until a `checklist_result` for this template is recorded against the task — hubOS's 'checklist for inspection' building toggle, per list instead of per building. One active template per (scope, task type, room type): re-defining one revises its items in place. A public-area task type's list may name a kind of area instead (`applies_to_area_kind`, 2026-10-14): an area's task resolves the list for its kind before the list for every area, at the house and then the brand.", "operationId": "get_hospitality_checklist_template_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.checklist_template" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.checklist_template:read" ] } ], "summary": "Read Checklist template as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.checklist_template/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe list an attendant ticks — or a supervisor inspects against — for one housekeeping task type, optionally one room type (`checklist_template_for_room_type`). A brand standard (`checklist_template_at_brand`) or the house's own (`checklist_template_at_property`); a task resolves the most specific active template: the house's for its room type, the house's for every room, the brand's for its room type, the brand's for every room. `required_for_completion` makes `complete_housekeeping_task` refuse until a `checklist_result` for this template is recorded against the task — hubOS's 'checklist for inspection' building toggle, per list instead of per building. One active template per (scope, task type, room type): re-defining one revises its items in place. A public-area task type's list may name a kind of area instead (`applies_to_area_kind`, 2026-10-14): an area's task resolves the list for its kind before the list for every area, at the house and then the brand.", "operationId": "list_links_hospitality_checklist_template", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.checklist_template:read" ] } ], "summary": "List links of Checklist template", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.checklist_result_for_template", "hospitality.link.checklist_template_at_brand", "hospitality.link.checklist_template_at_property", "hospitality.link.checklist_template_for_room_type" ] } } ] }, "/v1/object-types/hospitality.checklist_template/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe list an attendant ticks — or a supervisor inspects against — for one housekeeping task type, optionally one room type (`checklist_template_for_room_type`). A brand standard (`checklist_template_at_brand`) or the house's own (`checklist_template_at_property`); a task resolves the most specific active template: the house's for its room type, the house's for every room, the brand's for its room type, the brand's for every room. `required_for_completion` makes `complete_housekeeping_task` refuse until a `checklist_result` for this template is recorded against the task — hubOS's 'checklist for inspection' building toggle, per list instead of per building. One active template per (scope, task type, room type): re-defining one revises its items in place. A public-area task type's list may name a kind of area instead (`applies_to_area_kind`, 2026-10-14): an area's task resolves the list for its kind before the list for every area, at the house and then the brand.", "operationId": "traverse_hospitality_checklist_template", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.checklist_result_for_template", "hospitality.link.checklist_template_at_brand", "hospitality.link.checklist_template_at_property", "hospitality.link.checklist_template_for_room_type" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.checklist_template:read" ] } ], "summary": "Traverse from Checklist template", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.checklist_template/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe list an attendant ticks — or a supervisor inspects against — for one housekeeping task type, optionally one room type (`checklist_template_for_room_type`). A brand standard (`checklist_template_at_brand`) or the house's own (`checklist_template_at_property`); a task resolves the most specific active template: the house's for its room type, the house's for every room, the brand's for its room type, the brand's for every room. `required_for_completion` makes `complete_housekeeping_task` refuse until a `checklist_result` for this template is recorded against the task — hubOS's 'checklist for inspection' building toggle, per list instead of per building. One active template per (scope, task type, room type): re-defining one revises its items in place. A public-area task type's list may name a kind of area instead (`applies_to_area_kind`, 2026-10-14): an area's task resolves the list for its kind before the list for every area, at the house and then the brand.", "operationId": "search_hospitality_checklist_template", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applies_to_task_type" }, "type": { "const": "eq" }, "value": { "enum": [ "stayover", "departure", "vacant_pickup", "deep_clean", "turndown", "inspection", "public_area_clean", "public_area_inspection", "minibar", "laundry" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applies_to_area_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "lobby", "corridor", "lift", "stairwell", "pool", "gym", "spa_area", "restaurant_floor", "toilets", "back_of_house", "exterior", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "items" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "code": { "type": "string" }, "kind": { "enum": [ "check", "photo", "count", "text" ], "type": "string" }, "label": { "type": "string" } }, "required": [ "code", "label", "kind" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "required_for_completion" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "retired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "name", "applies_to_task_type", "applies_to_area_kind", "status", "retired_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.checklist_template" }, "properties": { "additionalProperties": false, "properties": { "applies_to_area_kind": { "enum": [ "lobby", "corridor", "lift", "stairwell", "pool", "gym", "spa_area", "restaurant_floor", "toilets", "back_of_house", "exterior", "other" ], "title": "The kind of public area the list is for (on a public-area task type only); absent: every area, or a room's list", "type": "string" }, "applies_to_task_type": { "enum": [ "stayover", "departure", "vacant_pickup", "deep_clean", "turndown", "inspection", "public_area_clean", "public_area_inspection", "minibar", "laundry" ], "title": "The housekeeping task type the list is for", "type": "string" }, "id": { "title": "Checklist template id", "type": "string" }, "items": { "description": "The items, in the order the attendant meets them", "items": { "properties": { "code": { "type": "string" }, "kind": { "enum": [ "check", "photo", "count", "text" ], "type": "string" }, "label": { "type": "string" } }, "required": [ "code", "label", "kind" ], "type": "object" }, "title": "Checklist template items", "type": "array" }, "name": { "title": "What the list is called on the handset", "type": "string" }, "required_for_completion": { "title": "Whether the task cannot complete without a recorded result", "type": "boolean" }, "retired_at": { "format": "date-time", "title": "When the template was retired", "type": "string" }, "status": { "enum": [ "active", "retired" ], "title": "Active (resolves onto tasks) or retired", "type": "string" } }, "required": [ "id", "name", "applies_to_task_type", "items", "required_for_completion", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.checklist_template:read" ] } ], "summary": "Search Checklist template", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.checkpoint_result/objects/{id}": { "get": { "description": "Read an existing instance.\n\nWhat one checkpoint of an inspection round recorded (`checkpoint_result_in_round`) — hubOS's revision chapter. The checkpoint's `checkpoint_position` and `kind` in the round, the room (`checkpoint_result_for_room`) or equipment (`checkpoint_result_for_asset`) it is at — neither for a general place — the answered `items`, the walker's `observations`, when it was started and finished (its duration is the difference), and who recorded it (`recorded_by`; `checkpoint_result_recorded_by` when a staff member did). `anomalies` is derived, never typed: the items answered not ok. `faults` counts the work orders raised from it (`work_order_from_checkpoint`). One result per round × checkpoint: recording the checkpoint again replaces it in place while the round is open. Its id may be the walker's own (a v4 or v7 UUID minted on the handset), so a photo taken with no signal waits for it. Photos hang off it as attachments; a checkpoint's `photo` items are answered by them, and the round does not complete without them.", "operationId": "get_hospitality_checkpoint_result", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.checkpoint_result" }, "properties": { "additionalProperties": false, "properties": { "anomalies": { "title": "Items answered not ok — derived from the items", "type": "integer" }, "checkpoint_position": { "title": "The checkpoint's position in the round", "type": "integer" }, "completed_at": { "format": "date-time", "title": "When the checkpoint was finished (the handset's own time when it says)", "type": "string" }, "faults": { "title": "Work orders raised from this checkpoint", "type": "integer" }, "id": { "title": "Checkpoint result id", "type": "string" }, "items": { "description": "The answered items, by the checkpoint's item codes", "items": { "properties": { "code": { "type": "string" }, "ok": { "type": "boolean" }, "text": { "type": "string" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "code" ], "type": "object" }, "title": "Checkpoint result items", "type": "array" }, "kind": { "enum": [ "room", "asset", "general" ], "title": "room, asset or general — the checkpoint's kind in the round", "type": "string" }, "observations": { "title": "What the walker noticed at the checkpoint", "type": "string" }, "recorded_by": { "title": "The principal that recorded it (`user:…`, `agent:…`, `service:…`, `system`)", "type": "string" }, "started_at": { "format": "date-time", "title": "When the walker began the checkpoint", "type": "string" } }, "required": [ "id", "checkpoint_position", "kind", "items", "anomalies", "faults", "completed_at", "recorded_by" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.checkpoint_result:read" ] } ], "summary": "Read Checkpoint result", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.checkpoint_result/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nWhat one checkpoint of an inspection round recorded (`checkpoint_result_in_round`) — hubOS's revision chapter. The checkpoint's `checkpoint_position` and `kind` in the round, the room (`checkpoint_result_for_room`) or equipment (`checkpoint_result_for_asset`) it is at — neither for a general place — the answered `items`, the walker's `observations`, when it was started and finished (its duration is the difference), and who recorded it (`recorded_by`; `checkpoint_result_recorded_by` when a staff member did). `anomalies` is derived, never typed: the items answered not ok. `faults` counts the work orders raised from it (`work_order_from_checkpoint`). One result per round × checkpoint: recording the checkpoint again replaces it in place while the round is open. Its id may be the walker's own (a v4 or v7 UUID minted on the handset), so a photo taken with no signal waits for it. Photos hang off it as attachments; a checkpoint's `photo` items are answered by them, and the round does not complete without them.", "operationId": "get_hospitality_checkpoint_result_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.checkpoint_result" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.checkpoint_result:read" ] } ], "summary": "Read Checkpoint result as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.checkpoint_result/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nWhat one checkpoint of an inspection round recorded (`checkpoint_result_in_round`) — hubOS's revision chapter. The checkpoint's `checkpoint_position` and `kind` in the round, the room (`checkpoint_result_for_room`) or equipment (`checkpoint_result_for_asset`) it is at — neither for a general place — the answered `items`, the walker's `observations`, when it was started and finished (its duration is the difference), and who recorded it (`recorded_by`; `checkpoint_result_recorded_by` when a staff member did). `anomalies` is derived, never typed: the items answered not ok. `faults` counts the work orders raised from it (`work_order_from_checkpoint`). One result per round × checkpoint: recording the checkpoint again replaces it in place while the round is open. Its id may be the walker's own (a v4 or v7 UUID minted on the handset), so a photo taken with no signal waits for it. Photos hang off it as attachments; a checkpoint's `photo` items are answered by them, and the round does not complete without them.", "operationId": "list_links_hospitality_checkpoint_result", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.checkpoint_result:read" ] } ], "summary": "List links of Checkpoint result", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.checkpoint_result_for_asset", "hospitality.link.checkpoint_result_for_room", "hospitality.link.checkpoint_result_in_round", "hospitality.link.checkpoint_result_recorded_by", "hospitality.link.stored_object_for_checkpoint_result", "hospitality.link.work_order_from_checkpoint" ] } } ] }, "/v1/object-types/hospitality.checkpoint_result/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nWhat one checkpoint of an inspection round recorded (`checkpoint_result_in_round`) — hubOS's revision chapter. The checkpoint's `checkpoint_position` and `kind` in the round, the room (`checkpoint_result_for_room`) or equipment (`checkpoint_result_for_asset`) it is at — neither for a general place — the answered `items`, the walker's `observations`, when it was started and finished (its duration is the difference), and who recorded it (`recorded_by`; `checkpoint_result_recorded_by` when a staff member did). `anomalies` is derived, never typed: the items answered not ok. `faults` counts the work orders raised from it (`work_order_from_checkpoint`). One result per round × checkpoint: recording the checkpoint again replaces it in place while the round is open. Its id may be the walker's own (a v4 or v7 UUID minted on the handset), so a photo taken with no signal waits for it. Photos hang off it as attachments; a checkpoint's `photo` items are answered by them, and the round does not complete without them.", "operationId": "traverse_hospitality_checkpoint_result", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.checkpoint_result_for_asset", "hospitality.link.checkpoint_result_for_room", "hospitality.link.checkpoint_result_in_round", "hospitality.link.checkpoint_result_recorded_by", "hospitality.link.stored_object_for_checkpoint_result", "hospitality.link.work_order_from_checkpoint" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.checkpoint_result:read" ] } ], "summary": "Traverse from Checkpoint result", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.checkpoint_result/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nWhat one checkpoint of an inspection round recorded (`checkpoint_result_in_round`) — hubOS's revision chapter. The checkpoint's `checkpoint_position` and `kind` in the round, the room (`checkpoint_result_for_room`) or equipment (`checkpoint_result_for_asset`) it is at — neither for a general place — the answered `items`, the walker's `observations`, when it was started and finished (its duration is the difference), and who recorded it (`recorded_by`; `checkpoint_result_recorded_by` when a staff member did). `anomalies` is derived, never typed: the items answered not ok. `faults` counts the work orders raised from it (`work_order_from_checkpoint`). One result per round × checkpoint: recording the checkpoint again replaces it in place while the round is open. Its id may be the walker's own (a v4 or v7 UUID minted on the handset), so a photo taken with no signal waits for it. Photos hang off it as attachments; a checkpoint's `photo` items are answered by them, and the round does not complete without them.", "operationId": "search_hospitality_checkpoint_result", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checkpoint_position" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checkpoint_position" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checkpoint_position" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "room", "asset", "general" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "items" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "code": { "type": "string" }, "ok": { "type": "boolean" }, "text": { "type": "string" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "code" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "observations" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "observations" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "anomalies" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "anomalies" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "anomalies" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "faults" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "faults" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "faults" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "checkpoint_position", "kind", "observations", "anomalies", "faults", "started_at", "completed_at", "recorded_by" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.checkpoint_result" }, "properties": { "additionalProperties": false, "properties": { "anomalies": { "title": "Items answered not ok — derived from the items", "type": "integer" }, "checkpoint_position": { "title": "The checkpoint's position in the round", "type": "integer" }, "completed_at": { "format": "date-time", "title": "When the checkpoint was finished (the handset's own time when it says)", "type": "string" }, "faults": { "title": "Work orders raised from this checkpoint", "type": "integer" }, "id": { "title": "Checkpoint result id", "type": "string" }, "items": { "description": "The answered items, by the checkpoint's item codes", "items": { "properties": { "code": { "type": "string" }, "ok": { "type": "boolean" }, "text": { "type": "string" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "code" ], "type": "object" }, "title": "Checkpoint result items", "type": "array" }, "kind": { "enum": [ "room", "asset", "general" ], "title": "room, asset or general — the checkpoint's kind in the round", "type": "string" }, "observations": { "title": "What the walker noticed at the checkpoint", "type": "string" }, "recorded_by": { "title": "The principal that recorded it (`user:…`, `agent:…`, `service:…`, `system`)", "type": "string" }, "started_at": { "format": "date-time", "title": "When the walker began the checkpoint", "type": "string" } }, "required": [ "id", "checkpoint_position", "kind", "items", "anomalies", "faults", "completed_at", "recorded_by" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.checkpoint_result:read" ] } ], "summary": "Search Checkpoint result", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.coaching_plan/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe non-clinical operational counterpart to `wellness_protocol`. A narrative trajectory across multiple protocols, lifestyle work, and check-in cadence. Distinct from the protocol because the protocol is a typed modality-pattern prescription and the coaching plan is the broader member trajectory across them.", "operationId": "get_hospitality_coaching_plan", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.coaching_plan" }, "properties": { "additionalProperties": false, "properties": { "coach_staff_ref": { "format": "uuid", "title": "Coach (typed reference when staff)", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "coach_text": { "title": "Coach identifier (free text — practitioner may not be staff)", "type": "string" }, "current_focus_text": { "title": "Current focus (member's working priority this cycle)", "type": "string" }, "id": { "title": "Coaching plan id", "type": "string" }, "is_active": { "title": "Currently active", "type": "boolean" }, "next_review_date": { "format": "date", "title": "Next review date (typically 4 / 8 / 12-week cycle)", "type": "string" }, "protocol_summary_text": { "title": "Operator's running narrative across the member's protocols", "type": "string" }, "started_at": { "format": "date-time", "title": "When coaching began", "type": "string" } }, "required": [ "id", "started_at", "is_active" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.coaching_plan:read" ] } ], "summary": "Read Coaching plan", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.coaching_plan/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe non-clinical operational counterpart to `wellness_protocol`. A narrative trajectory across multiple protocols, lifestyle work, and check-in cadence. Distinct from the protocol because the protocol is a typed modality-pattern prescription and the coaching plan is the broader member trajectory across them.", "operationId": "get_hospitality_coaching_plan_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.coaching_plan" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.coaching_plan:read" ] } ], "summary": "Read Coaching plan as of a watermark", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.coaching_plan/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe non-clinical operational counterpart to `wellness_protocol`. A narrative trajectory across multiple protocols, lifestyle work, and check-in cadence. Distinct from the protocol because the protocol is a typed modality-pattern prescription and the coaching plan is the broader member trajectory across them.", "operationId": "list_links_hospitality_coaching_plan", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.coaching_plan:read" ] } ], "summary": "List links of Coaching plan", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.coaching_plan_for_membership", "hospitality.link.coaching_plan_references_protocol" ] } } ] }, "/v1/object-types/hospitality.coaching_plan/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe non-clinical operational counterpart to `wellness_protocol`. A narrative trajectory across multiple protocols, lifestyle work, and check-in cadence. Distinct from the protocol because the protocol is a typed modality-pattern prescription and the coaching plan is the broader member trajectory across them.", "operationId": "traverse_hospitality_coaching_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.coaching_plan_for_membership", "hospitality.link.coaching_plan_references_protocol" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.coaching_plan:read" ] } ], "summary": "Traverse from Coaching plan", "tags": [ "membership" ] } }, "/v1/object-types/hospitality.coaching_plan/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe non-clinical operational counterpart to `wellness_protocol`. A narrative trajectory across multiple protocols, lifestyle work, and check-in cadence. Distinct from the protocol because the protocol is a typed modality-pattern prescription and the coaching plan is the broader member trajectory across them.", "operationId": "search_hospitality_coaching_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "coach_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "coach_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "coach_text" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "coach_text" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "coach_staff_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "current_focus_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "current_focus_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_review_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_review_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_review_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "protocol_summary_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "protocol_summary_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "is_active" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "started_at", "coach_text", "current_focus_text", "next_review_date", "protocol_summary_text" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.coaching_plan" }, "properties": { "additionalProperties": false, "properties": { "coach_staff_ref": { "format": "uuid", "title": "Coach (typed reference when staff)", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "coach_text": { "title": "Coach identifier (free text — practitioner may not be staff)", "type": "string" }, "current_focus_text": { "title": "Current focus (member's working priority this cycle)", "type": "string" }, "id": { "title": "Coaching plan id", "type": "string" }, "is_active": { "title": "Currently active", "type": "boolean" }, "next_review_date": { "format": "date", "title": "Next review date (typically 4 / 8 / 12-week cycle)", "type": "string" }, "protocol_summary_text": { "title": "Operator's running narrative across the member's protocols", "type": "string" }, "started_at": { "format": "date-time", "title": "When coaching began", "type": "string" } }, "required": [ "id", "started_at", "is_active" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.coaching_plan:read" ] } ], "summary": "Search Coaching plan", "tags": [ "membership" ] } }, "/v1/object-types/hospitality.commission_agreement/objects/{id}": { "get": { "description": "Read an existing instance.\n\nTime-varying commission contract between a property and a travel agent, tour operator, wholesaler or consortium. Carries the rate, kind and flat amount in effect for the period, plus the minimum the agent will accept a payment for. Only one row per (company, property) may be open at a time; binding a new one closes the last.", "operationId": "get_hospitality_commission_agreement", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.commission_agreement" }, "properties": { "additionalProperties": false, "properties": { "commission_flat_amount": { "description": "Per-booking flat commission", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Commission agreement commission flat amount", "type": "object" }, "commission_kind": { "enum": [ "percent_of_revenue", "per_booking_flat", "per_booking_plus_percent", "none" ], "title": "Commission kind", "type": "string" }, "commission_rate": { "format": "decimal", "title": "Commission rate (decimal share of commissionable revenue)", "type": "string" }, "effective_from": { "format": "date", "title": "Effective from", "type": "string" }, "effective_to": { "format": "date", "title": "Effective to (null = currently in effect)", "type": "string" }, "id": { "title": "Agreement id", "type": "string" }, "minimum_payment_amount": { "description": "Do not pay this agent below this amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Commission agreement minimum payment amount", "type": "object" }, "notes": { "title": "Contract notes", "type": "string" }, "tax_treatment": { "enum": [ "standard", "reverse_charge", "exempt" ], "title": "VAT posture of this agent's commission", "type": "string" } }, "required": [ "id", "effective_from", "commission_kind" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.commission_agreement:read" ] } ], "summary": "Read Commission agreement", "tags": [ "commission" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.commission_agreement/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nTime-varying commission contract between a property and a travel agent, tour operator, wholesaler or consortium. Carries the rate, kind and flat amount in effect for the period, plus the minimum the agent will accept a payment for. Only one row per (company, property) may be open at a time; binding a new one closes the last.", "operationId": "get_hospitality_commission_agreement_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.commission_agreement" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.commission_agreement:read" ] } ], "summary": "Read Commission agreement as of a watermark", "tags": [ "commission" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.commission_agreement/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nTime-varying commission contract between a property and a travel agent, tour operator, wholesaler or consortium. Carries the rate, kind and flat amount in effect for the period, plus the minimum the agent will accept a payment for. Only one row per (company, property) may be open at a time; binding a new one closes the last.", "operationId": "list_links_hospitality_commission_agreement", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.commission_agreement:read" ] } ], "summary": "List links of Commission agreement", "tags": [ "commission" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.commission_agreement_for_company", "hospitality.link.commission_agreement_for_property" ] } } ] }, "/v1/object-types/hospitality.commission_agreement/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nTime-varying commission contract between a property and a travel agent, tour operator, wholesaler or consortium. Carries the rate, kind and flat amount in effect for the period, plus the minimum the agent will accept a payment for. Only one row per (company, property) may be open at a time; binding a new one closes the last.", "operationId": "traverse_hospitality_commission_agreement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.commission_agreement_for_company", "hospitality.link.commission_agreement_for_property" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.commission_agreement:read" ] } ], "summary": "Traverse from Commission agreement", "tags": [ "commission" ] } }, "/v1/object-types/hospitality.commission_agreement/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nTime-varying commission contract between a property and a travel agent, tour operator, wholesaler or consortium. Carries the rate, kind and flat amount in effect for the period, plus the minimum the agent will accept a payment for. Only one row per (company, property) may be open at a time; binding a new one closes the last.", "operationId": "search_hospitality_commission_agreement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commission_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "percent_of_revenue", "per_booking_flat", "per_booking_plus_percent", "none" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commission_rate" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commission_rate" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commission_rate" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commission_flat_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "minimum_payment_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_treatment" }, "type": { "const": "eq" }, "value": { "enum": [ "standard", "reverse_charge", "exempt" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "effective_from", "effective_to", "commission_kind", "commission_rate", "tax_treatment", "notes" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.commission_agreement" }, "properties": { "additionalProperties": false, "properties": { "commission_flat_amount": { "description": "Per-booking flat commission", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Commission agreement commission flat amount", "type": "object" }, "commission_kind": { "enum": [ "percent_of_revenue", "per_booking_flat", "per_booking_plus_percent", "none" ], "title": "Commission kind", "type": "string" }, "commission_rate": { "format": "decimal", "title": "Commission rate (decimal share of commissionable revenue)", "type": "string" }, "effective_from": { "format": "date", "title": "Effective from", "type": "string" }, "effective_to": { "format": "date", "title": "Effective to (null = currently in effect)", "type": "string" }, "id": { "title": "Agreement id", "type": "string" }, "minimum_payment_amount": { "description": "Do not pay this agent below this amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Commission agreement minimum payment amount", "type": "object" }, "notes": { "title": "Contract notes", "type": "string" }, "tax_treatment": { "enum": [ "standard", "reverse_charge", "exempt" ], "title": "VAT posture of this agent's commission", "type": "string" } }, "required": [ "id", "effective_from", "commission_kind" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.commission_agreement:read" ] } ], "summary": "Search Commission agreement", "tags": [ "commission" ] } }, "/v1/object-types/hospitality.commission_detail/objects/{id}": { "get": { "description": "Read an existing instance.\n\nWhat one completed stay owes one payee. `settlement_mode` says whether this is a payable the hotel initiates (a travel agent) or an expectation to reconcile against an invoice the payee will send us (an agency-model OTA) — the two look identical on a reservation and must never be paid the same way. The rate and policy that produced the amount are frozen on the row, so a later renegotiation cannot restate a historical liability.", "operationId": "get_hospitality_commission_detail", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.commission_detail" }, "properties": { "additionalProperties": false, "properties": { "accrued_on": { "format": "date", "title": "Business date the stay completed", "type": "string" }, "adjusted_from_amount": { "description": "Amount before the operator adjusted it", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Commission detail adjusted from amount", "type": "object" }, "commission_amount": { "description": "Amount owed to the payee", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Commission detail commission amount", "type": "object" }, "commission_kind": { "enum": [ "percent_of_revenue", "per_booking_flat", "per_booking_plus_percent", "none" ], "title": "Commission kind in force at accrual", "type": "string" }, "commission_rate": { "format": "decimal", "title": "Commission rate in force at accrual", "type": "string" }, "commissionable_revenue": { "description": "Revenue the commission was computed on, in property currency", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Commission detail commissionable revenue", "type": "object" }, "hold_reason": { "title": "Why the row is held back from payment", "type": "string" }, "id": { "title": "Detail id", "type": "string" }, "payee_kind": { "enum": [ "company", "channel" ], "title": "Whether the payee is a company or a channel", "type": "string" }, "policy_ref": { "title": "Agreement or channel period the figures were derived from", "type": "string" }, "settled_reason": { "title": "Why the row settled without a payment", "type": "string" }, "settlement_mode": { "enum": [ "payable", "reconcile" ], "title": "Hotel-initiated payable, or an invoice to reconcile", "type": "string" }, "status": { "enum": [ "accrued", "held", "paid", "reconciled", "prepaid", "offset_to_ar", "voided" ], "title": "Detail status", "type": "string" }, "tax_treatment": { "enum": [ "standard", "reverse_charge", "exempt" ], "title": "VAT posture of this amount", "type": "string" } }, "required": [ "id", "status", "payee_kind", "settlement_mode", "accrued_on", "commission_kind" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.commission_detail:read" ] } ], "summary": "Read Commission detail", "tags": [ "commission" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.commission_detail/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nWhat one completed stay owes one payee. `settlement_mode` says whether this is a payable the hotel initiates (a travel agent) or an expectation to reconcile against an invoice the payee will send us (an agency-model OTA) — the two look identical on a reservation and must never be paid the same way. The rate and policy that produced the amount are frozen on the row, so a later renegotiation cannot restate a historical liability.", "operationId": "get_hospitality_commission_detail_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.commission_detail" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.commission_detail:read" ] } ], "summary": "Read Commission detail as of a watermark", "tags": [ "commission" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.commission_detail/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nWhat one completed stay owes one payee. `settlement_mode` says whether this is a payable the hotel initiates (a travel agent) or an expectation to reconcile against an invoice the payee will send us (an agency-model OTA) — the two look identical on a reservation and must never be paid the same way. The rate and policy that produced the amount are frozen on the row, so a later renegotiation cannot restate a historical liability.", "operationId": "list_links_hospitality_commission_detail", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.commission_detail:read" ] } ], "summary": "List links of Commission detail", "tags": [ "commission" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.commission_detail_for_reservation", "hospitality.link.commission_detail_in_batch", "hospitality.link.commission_detail_owed_to_channel", "hospitality.link.commission_detail_owed_to_company" ] } } ] }, "/v1/object-types/hospitality.commission_detail/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nWhat one completed stay owes one payee. `settlement_mode` says whether this is a payable the hotel initiates (a travel agent) or an expectation to reconcile against an invoice the payee will send us (an agency-model OTA) — the two look identical on a reservation and must never be paid the same way. The rate and policy that produced the amount are frozen on the row, so a later renegotiation cannot restate a historical liability.", "operationId": "traverse_hospitality_commission_detail", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.commission_detail_for_reservation", "hospitality.link.commission_detail_in_batch", "hospitality.link.commission_detail_owed_to_channel", "hospitality.link.commission_detail_owed_to_company" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.commission_detail:read" ] } ], "summary": "Traverse from Commission detail", "tags": [ "commission" ] } }, "/v1/object-types/hospitality.commission_detail/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nWhat one completed stay owes one payee. `settlement_mode` says whether this is a payable the hotel initiates (a travel agent) or an expectation to reconcile against an invoice the payee will send us (an agency-model OTA) — the two look identical on a reservation and must never be paid the same way. The rate and policy that produced the amount are frozen on the row, so a later renegotiation cannot restate a historical liability.", "operationId": "search_hospitality_commission_detail", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "accrued", "held", "paid", "reconciled", "prepaid", "offset_to_ar", "voided" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payee_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "company", "channel" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "settlement_mode" }, "type": { "const": "eq" }, "value": { "enum": [ "payable", "reconcile" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "accrued_on" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "accrued_on" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "accrued_on" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commissionable_revenue" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commission_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commission_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "percent_of_revenue", "per_booking_flat", "per_booking_plus_percent", "none" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commission_rate" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commission_rate" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commission_rate" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "policy_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "policy_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "policy_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "policy_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_treatment" }, "type": { "const": "eq" }, "value": { "enum": [ "standard", "reverse_charge", "exempt" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "settled_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "settled_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "adjusted_from_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "status", "payee_kind", "settlement_mode", "accrued_on", "commission_kind", "commission_rate", "policy_ref", "tax_treatment", "hold_reason", "settled_reason" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.commission_detail" }, "properties": { "additionalProperties": false, "properties": { "accrued_on": { "format": "date", "title": "Business date the stay completed", "type": "string" }, "adjusted_from_amount": { "description": "Amount before the operator adjusted it", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Commission detail adjusted from amount", "type": "object" }, "commission_amount": { "description": "Amount owed to the payee", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Commission detail commission amount", "type": "object" }, "commission_kind": { "enum": [ "percent_of_revenue", "per_booking_flat", "per_booking_plus_percent", "none" ], "title": "Commission kind in force at accrual", "type": "string" }, "commission_rate": { "format": "decimal", "title": "Commission rate in force at accrual", "type": "string" }, "commissionable_revenue": { "description": "Revenue the commission was computed on, in property currency", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Commission detail commissionable revenue", "type": "object" }, "hold_reason": { "title": "Why the row is held back from payment", "type": "string" }, "id": { "title": "Detail id", "type": "string" }, "payee_kind": { "enum": [ "company", "channel" ], "title": "Whether the payee is a company or a channel", "type": "string" }, "policy_ref": { "title": "Agreement or channel period the figures were derived from", "type": "string" }, "settled_reason": { "title": "Why the row settled without a payment", "type": "string" }, "settlement_mode": { "enum": [ "payable", "reconcile" ], "title": "Hotel-initiated payable, or an invoice to reconcile", "type": "string" }, "status": { "enum": [ "accrued", "held", "paid", "reconciled", "prepaid", "offset_to_ar", "voided" ], "title": "Detail status", "type": "string" }, "tax_treatment": { "enum": [ "standard", "reverse_charge", "exempt" ], "title": "VAT posture of this amount", "type": "string" } }, "required": [ "id", "status", "payee_kind", "settlement_mode", "accrued_on", "commission_kind" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.commission_detail:read" ] } ], "summary": "Search Commission detail", "tags": [ "commission" ] } }, "/v1/object-types/hospitality.commission_payment_batch/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne payment run over approved commission details. Paying the batch freezes its rows; voiding it releases them back to `approved` for a later run. `settlement_network` records that the batch went to a clearinghouse without this kernel pretending to speak their file format.", "operationId": "get_hospitality_commission_payment_batch", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.commission_payment_batch" }, "properties": { "additionalProperties": false, "properties": { "detail_count": { "title": "How many details the batch settled", "type": "integer" }, "id": { "title": "Batch id", "type": "string" }, "method": { "enum": [ "check", "bank_transfer", "settlement_network", "manual" ], "title": "How the batch paid out", "type": "string" }, "paid_at": { "format": "date-time", "title": "When the batch paid", "type": "string" }, "reference": { "title": "Cheque number, transfer reference or clearinghouse batch id", "type": "string" }, "status": { "enum": [ "open", "paid", "voided" ], "title": "Batch status", "type": "string" }, "total_amount": { "description": "Total paid", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Commission payment batch total amount", "type": "object" } }, "required": [ "id", "status", "method" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.commission_payment_batch:read" ] } ], "summary": "Read Commission payment batch", "tags": [ "commission" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.commission_payment_batch/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne payment run over approved commission details. Paying the batch freezes its rows; voiding it releases them back to `approved` for a later run. `settlement_network` records that the batch went to a clearinghouse without this kernel pretending to speak their file format.", "operationId": "get_hospitality_commission_payment_batch_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.commission_payment_batch" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.commission_payment_batch:read" ] } ], "summary": "Read Commission payment batch as of a watermark", "tags": [ "commission" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.commission_payment_batch/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne payment run over approved commission details. Paying the batch freezes its rows; voiding it releases them back to `approved` for a later run. `settlement_network` records that the batch went to a clearinghouse without this kernel pretending to speak their file format.", "operationId": "list_links_hospitality_commission_payment_batch", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.commission_payment_batch:read" ] } ], "summary": "List links of Commission payment batch", "tags": [ "commission" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.commission_batch_for_property", "hospitality.link.commission_detail_in_batch" ] } } ] }, "/v1/object-types/hospitality.commission_payment_batch/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne payment run over approved commission details. Paying the batch freezes its rows; voiding it releases them back to `approved` for a later run. `settlement_network` records that the batch went to a clearinghouse without this kernel pretending to speak their file format.", "operationId": "traverse_hospitality_commission_payment_batch", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.commission_batch_for_property", "hospitality.link.commission_detail_in_batch" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.commission_payment_batch:read" ] } ], "summary": "Traverse from Commission payment batch", "tags": [ "commission" ] } }, "/v1/object-types/hospitality.commission_payment_batch/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne payment run over approved commission details. Paying the batch freezes its rows; voiding it releases them back to `approved` for a later run. `settlement_network` records that the batch went to a clearinghouse without this kernel pretending to speak their file format.", "operationId": "search_hospitality_commission_payment_batch", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "open", "paid", "voided" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "method" }, "type": { "const": "eq" }, "value": { "enum": [ "check", "bank_transfer", "settlement_network", "manual" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "total_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "detail_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "detail_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "detail_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "paid_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "paid_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "paid_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "status", "method", "detail_count", "reference", "paid_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.commission_payment_batch" }, "properties": { "additionalProperties": false, "properties": { "detail_count": { "title": "How many details the batch settled", "type": "integer" }, "id": { "title": "Batch id", "type": "string" }, "method": { "enum": [ "check", "bank_transfer", "settlement_network", "manual" ], "title": "How the batch paid out", "type": "string" }, "paid_at": { "format": "date-time", "title": "When the batch paid", "type": "string" }, "reference": { "title": "Cheque number, transfer reference or clearinghouse batch id", "type": "string" }, "status": { "enum": [ "open", "paid", "voided" ], "title": "Batch status", "type": "string" }, "total_amount": { "description": "Total paid", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Commission payment batch total amount", "type": "object" } }, "required": [ "id", "status", "method" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.commission_payment_batch:read" ] } ], "summary": "Search Commission payment batch", "tags": [ "commission" ] } }, "/v1/object-types/hospitality.comp_authority_policy/objects/{id}": { "get": { "description": "Read an existing instance.\n\nProperty-scoped comp-authority row keyed on (role, comp_category). The recovery handler resolves staff authority by looking up policy rows; the cache on `staff_member.comp_authority_summary` is the hot-path read.", "operationId": "get_hospitality_comp_authority_policy", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.comp_authority_policy" }, "properties": { "additionalProperties": false, "properties": { "comp_category": { "enum": [ "room_night", "food_beverage", "spa", "retail", "parking", "other" ], "title": "Comp category", "type": "string" }, "id": { "title": "Policy id", "type": "string" }, "limit_per_day": { "description": "Limit per day", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Comp authority policy limit per day", "type": "object" }, "limit_per_incident": { "description": "Limit per incident", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Comp authority policy limit per incident", "type": "object" }, "limit_per_stay": { "description": "Limit per stay", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Comp authority policy limit per stay", "type": "object" }, "requires_escalation_above": { "description": "Escalation threshold (soft)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Comp authority policy requires escalation above", "type": "object" }, "role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "Role", "type": "string" } }, "required": [ "id", "role", "comp_category" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.comp_authority_policy:read" ] } ], "summary": "Read Comp authority policy", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.comp_authority_policy/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nProperty-scoped comp-authority row keyed on (role, comp_category). The recovery handler resolves staff authority by looking up policy rows; the cache on `staff_member.comp_authority_summary` is the hot-path read.", "operationId": "get_hospitality_comp_authority_policy_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.comp_authority_policy" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.comp_authority_policy:read" ] } ], "summary": "Read Comp authority policy as of a watermark", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.comp_authority_policy/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nProperty-scoped comp-authority row keyed on (role, comp_category). The recovery handler resolves staff authority by looking up policy rows; the cache on `staff_member.comp_authority_summary` is the hot-path read.", "operationId": "list_links_hospitality_comp_authority_policy", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.comp_authority_policy:read" ] } ], "summary": "List links of Comp authority policy", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.comp_authority_policy_at_property" ] } } ] }, "/v1/object-types/hospitality.comp_authority_policy/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nProperty-scoped comp-authority row keyed on (role, comp_category). The recovery handler resolves staff authority by looking up policy rows; the cache on `staff_member.comp_authority_summary` is the hot-path read.", "operationId": "traverse_hospitality_comp_authority_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.comp_authority_policy_at_property" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.comp_authority_policy:read" ] } ], "summary": "Traverse from Comp authority policy", "tags": [ "people" ] } }, "/v1/object-types/hospitality.comp_authority_policy/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nProperty-scoped comp-authority row keyed on (role, comp_category). The recovery handler resolves staff authority by looking up policy rows; the cache on `staff_member.comp_authority_summary` is the hot-path read.", "operationId": "search_hospitality_comp_authority_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "role" }, "type": { "const": "eq" }, "value": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "comp_category" }, "type": { "const": "eq" }, "value": { "enum": [ "room_night", "food_beverage", "spa", "retail", "parking", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "limit_per_incident" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "limit_per_day" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "limit_per_stay" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requires_escalation_above" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "role", "comp_category" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.comp_authority_policy" }, "properties": { "additionalProperties": false, "properties": { "comp_category": { "enum": [ "room_night", "food_beverage", "spa", "retail", "parking", "other" ], "title": "Comp category", "type": "string" }, "id": { "title": "Policy id", "type": "string" }, "limit_per_day": { "description": "Limit per day", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Comp authority policy limit per day", "type": "object" }, "limit_per_incident": { "description": "Limit per incident", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Comp authority policy limit per incident", "type": "object" }, "limit_per_stay": { "description": "Limit per stay", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Comp authority policy limit per stay", "type": "object" }, "requires_escalation_above": { "description": "Escalation threshold (soft)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Comp authority policy requires escalation above", "type": "object" }, "role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "Role", "type": "string" } }, "required": [ "id", "role", "comp_category" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.comp_authority_policy:read" ] } ], "summary": "Search Comp authority policy", "tags": [ "people" ] } }, "/v1/object-types/hospitality.company/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA corporate or trade account: corporate negotiated, travel agent, tour operator, wholesaler, group bookers. Used for billing, channel routing, and rate eligibility.", "operationId": "get_hospitality_company", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.company" }, "properties": { "additionalProperties": false, "properties": { "billing_address": { "description": "Billing address", "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "title": "Company billing address", "type": "object" }, "code": { "title": "Company code", "type": "string" }, "iata_number": { "title": "IATA number", "type": "string" }, "invoicing_email": { "description": "Where this company's invoices are sent — accounts payable, not the booker. Mews keeps the same field for the same reason: a company bill goes to the company's invoicing email, never to whoever made the reservation.", "title": "Invoicing email", "type": "string" }, "kind": { "enum": [ "corporate", "travel_agent", "tour_operator", "wholesaler", "government", "group", "ota", "consortia", "designer", "hotel_owner", "management_company" ], "title": "Company kind", "type": "string" }, "name": { "title": "Company name", "type": "string" }, "registration_number": { "description": "Companies-House-style registration number.", "title": "Company registration number", "type": "string" }, "tax_identifier": { "description": "The company's VAT / tax registration number, as printed on an invoice addressed to it. This is what makes the document usable for their input-tax recovery, which is the whole reason a company wants one.", "title": "Tax identifier", "type": "string" } }, "required": [ "code", "name", "kind" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.company:read" ] } ], "summary": "Read Company", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.company/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA corporate or trade account: corporate negotiated, travel agent, tour operator, wholesaler, group bookers. Used for billing, channel routing, and rate eligibility.", "operationId": "get_hospitality_company_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.company" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.company:read" ] } ], "summary": "Read Company as of a watermark", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.company/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA corporate or trade account: corporate negotiated, travel agent, tour operator, wholesaler, group bookers. Used for billing, channel routing, and rate eligibility.", "operationId": "list_links_hospitality_company", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.company:read" ] } ], "summary": "List links of Company", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.brand_operator_cost_for_company", "hospitality.link.commission_agreement_for_company", "hospitality.link.commission_detail_owed_to_company", "hospitality.link.company_has_ar_folio", "hospitality.link.design_dna_designed_by_company", "hospitality.link.external_record_reference_for_provider", "hospitality.link.invoice_billed_to_company", "hospitality.link.management_agreement_with_company", "hospitality.link.property_owned_by_company", "hospitality.link.reciprocity_agreement_between_orgs", "hospitality.link.reservation_for_company", "hospitality.link.venue_brand_owned_by_company", "hospitality.link.venue_has_operator", "hospitality.link.venue_residency" ] } } ] }, "/v1/object-types/hospitality.company/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA corporate or trade account: corporate negotiated, travel agent, tour operator, wholesaler, group bookers. Used for billing, channel routing, and rate eligibility.", "operationId": "traverse_hospitality_company", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.brand_operator_cost_for_company", "hospitality.link.commission_agreement_for_company", "hospitality.link.commission_detail_owed_to_company", "hospitality.link.company_has_ar_folio", "hospitality.link.design_dna_designed_by_company", "hospitality.link.external_record_reference_for_provider", "hospitality.link.invoice_billed_to_company", "hospitality.link.management_agreement_with_company", "hospitality.link.property_owned_by_company", "hospitality.link.reciprocity_agreement_between_orgs", "hospitality.link.reservation_for_company", "hospitality.link.venue_brand_owned_by_company", "hospitality.link.venue_has_operator", "hospitality.link.venue_residency" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.company:read" ] } ], "summary": "Traverse from Company", "tags": [ "people" ] } }, "/v1/object-types/hospitality.company/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA corporate or trade account: corporate negotiated, travel agent, tour operator, wholesaler, group bookers. Used for billing, channel routing, and rate eligibility.", "operationId": "search_hospitality_company", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "corporate", "travel_agent", "tour_operator", "wholesaler", "government", "group", "ota", "consortia", "designer", "hotel_owner", "management_company" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "billing_address" }, "type": { "const": "eq" }, "value": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "iata_number" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "iata_number" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "iata_number" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "iata_number" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_identifier" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_identifier" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_identifier" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_identifier" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "registration_number" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "registration_number" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "registration_number" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "registration_number" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "invoicing_email" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "invoicing_email" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "invoicing_email" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "invoicing_email" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "kind", "iata_number", "tax_identifier", "registration_number", "invoicing_email" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.company" }, "properties": { "additionalProperties": false, "properties": { "billing_address": { "description": "Billing address", "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "title": "Company billing address", "type": "object" }, "code": { "title": "Company code", "type": "string" }, "iata_number": { "title": "IATA number", "type": "string" }, "invoicing_email": { "description": "Where this company's invoices are sent — accounts payable, not the booker. Mews keeps the same field for the same reason: a company bill goes to the company's invoicing email, never to whoever made the reservation.", "title": "Invoicing email", "type": "string" }, "kind": { "enum": [ "corporate", "travel_agent", "tour_operator", "wholesaler", "government", "group", "ota", "consortia", "designer", "hotel_owner", "management_company" ], "title": "Company kind", "type": "string" }, "name": { "title": "Company name", "type": "string" }, "registration_number": { "description": "Companies-House-style registration number.", "title": "Company registration number", "type": "string" }, "tax_identifier": { "description": "The company's VAT / tax registration number, as printed on an invoice addressed to it. This is what makes the document usable for their input-tax recovery, which is the whole reason a company wants one.", "title": "Tax identifier", "type": "string" } }, "required": [ "code", "name", "kind" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.company:read" ] } ], "summary": "Search Company", "tags": [ "people" ] } }, "/v1/object-types/hospitality.connector/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe registered instance of one external source-system feed into the ontology (a property's PMS, POS back-end, rostering tool). Identity + lifecycle only: credentials live in the secret store (`secret_ref` is a name, never a value), sync cursors live in the raw staging schema, and the mapping definitions are versioned repo files (`mapping_refs`, one name@version per vendor stream). Lifecycle mutations (pause / resume / retire / start sync) are Actions, so the who-and-when is in the immutable events audit trail.", "operationId": "get_hospitality_connector", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector" }, "properties": { "additionalProperties": false, "properties": { "cut_over_at": { "format": "date-time", "title": "When the house cut over from this source (absent while shadowing)", "type": "string" }, "cut_over_by": { "title": "Principal::stable_id() of who took the cutover decision", "type": "string" }, "cut_over_summary": { "title": "The shadow comparison the cutover was taken on (counts, channel connections activated)" }, "display_name": { "title": "Human-readable name shown in the Explorer", "type": "string" }, "id": { "title": "Connector id", "type": "string" }, "mapping_refs": { "items": { "type": "string" }, "title": "Mapping definition references (name@version per vendor stream, versioned repo files)", "type": "array" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "paused_reason": { "title": "Why the connector is paused (required while status = paused)", "type": "string" }, "provider": { "title": "Vendor identifier (mews / apaleo / ohip / …)", "type": "string" }, "registered_at": { "format": "date-time", "title": "When the connector was registered", "type": "string" }, "registered_by": { "title": "Principal::stable_id() of the registering principal", "type": "string" }, "schedule": { "title": "Intended sync cadence, cron form (informational; the worker owns scheduling)", "type": "string" }, "secret_ref": { "title": "Name of the credential in the external secret store (never the value)", "type": "string" }, "source_kind": { "enum": [ "pms", "pos", "rostering", "inventory", "accounting", "distribution", "other" ], "title": "Category of source system", "type": "string" }, "status": { "enum": [ "active", "paused", "retired" ], "title": "Connector lifecycle status", "type": "string" }, "vendor_config": { "title": "Non-secret vendor settings (base URL, site codes, streams)" } }, "required": [ "id", "display_name", "source_kind", "provider", "mapping_refs", "status", "registered_by", "registered_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.connector:read" ] } ], "summary": "Read Connector", "tags": [ "connectors" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.connector/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe registered instance of one external source-system feed into the ontology (a property's PMS, POS back-end, rostering tool). Identity + lifecycle only: credentials live in the secret store (`secret_ref` is a name, never a value), sync cursors live in the raw staging schema, and the mapping definitions are versioned repo files (`mapping_refs`, one name@version per vendor stream). Lifecycle mutations (pause / resume / retire / start sync) are Actions, so the who-and-when is in the immutable events audit trail.", "operationId": "get_hospitality_connector_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.connector" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.connector:read" ] } ], "summary": "Read Connector as of a watermark", "tags": [ "connectors" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.connector/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe registered instance of one external source-system feed into the ontology (a property's PMS, POS back-end, rostering tool). Identity + lifecycle only: credentials live in the secret store (`secret_ref` is a name, never a value), sync cursors live in the raw staging schema, and the mapping definitions are versioned repo files (`mapping_refs`, one name@version per vendor stream). Lifecycle mutations (pause / resume / retire / start sync) are Actions, so the who-and-when is in the immutable events audit trail.", "operationId": "list_links_hospitality_connector", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.connector:read" ] } ], "summary": "List links of Connector", "tags": [ "connectors" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.sync_run_for_connector" ] } } ] }, "/v1/object-types/hospitality.connector/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe registered instance of one external source-system feed into the ontology (a property's PMS, POS back-end, rostering tool). Identity + lifecycle only: credentials live in the secret store (`secret_ref` is a name, never a value), sync cursors live in the raw staging schema, and the mapping definitions are versioned repo files (`mapping_refs`, one name@version per vendor stream). Lifecycle mutations (pause / resume / retire / start sync) are Actions, so the who-and-when is in the immutable events audit trail.", "operationId": "traverse_hospitality_connector", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.sync_run_for_connector" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.connector:read" ] } ], "summary": "Traverse from Connector", "tags": [ "connectors" ] } }, "/v1/object-types/hospitality.connector/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe registered instance of one external source-system feed into the ontology (a property's PMS, POS back-end, rostering tool). Identity + lifecycle only: credentials live in the secret store (`secret_ref` is a name, never a value), sync cursors live in the raw staging schema, and the mapping definitions are versioned repo files (`mapping_refs`, one name@version per vendor stream). Lifecycle mutations (pause / resume / retire / start sync) are Actions, so the who-and-when is in the immutable events audit trail.", "operationId": "search_hospitality_connector", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "pms", "pos", "rostering", "inventory", "accounting", "distribution", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "mapping_refs" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "paused", "retired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "secret_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "secret_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "secret_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "secret_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor_config" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "schedule" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "schedule" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "schedule" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "schedule" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "registered_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "registered_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "registered_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "registered_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "registered_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "registered_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "registered_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "paused_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "paused_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cut_over_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cut_over_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cut_over_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cut_over_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cut_over_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cut_over_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cut_over_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cut_over_summary" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "display_name", "source_kind", "provider", "status", "secret_ref", "schedule", "registered_by", "registered_at", "paused_reason", "notes", "cut_over_at", "cut_over_by" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector" }, "properties": { "additionalProperties": false, "properties": { "cut_over_at": { "format": "date-time", "title": "When the house cut over from this source (absent while shadowing)", "type": "string" }, "cut_over_by": { "title": "Principal::stable_id() of who took the cutover decision", "type": "string" }, "cut_over_summary": { "title": "The shadow comparison the cutover was taken on (counts, channel connections activated)" }, "display_name": { "title": "Human-readable name shown in the Explorer", "type": "string" }, "id": { "title": "Connector id", "type": "string" }, "mapping_refs": { "items": { "type": "string" }, "title": "Mapping definition references (name@version per vendor stream, versioned repo files)", "type": "array" }, "notes": { "title": "Free-form operator notes", "type": "string" }, "paused_reason": { "title": "Why the connector is paused (required while status = paused)", "type": "string" }, "provider": { "title": "Vendor identifier (mews / apaleo / ohip / …)", "type": "string" }, "registered_at": { "format": "date-time", "title": "When the connector was registered", "type": "string" }, "registered_by": { "title": "Principal::stable_id() of the registering principal", "type": "string" }, "schedule": { "title": "Intended sync cadence, cron form (informational; the worker owns scheduling)", "type": "string" }, "secret_ref": { "title": "Name of the credential in the external secret store (never the value)", "type": "string" }, "source_kind": { "enum": [ "pms", "pos", "rostering", "inventory", "accounting", "distribution", "other" ], "title": "Category of source system", "type": "string" }, "status": { "enum": [ "active", "paused", "retired" ], "title": "Connector lifecycle status", "type": "string" }, "vendor_config": { "title": "Non-secret vendor settings (base URL, site codes, streams)" } }, "required": [ "id", "display_name", "source_kind", "provider", "mapping_refs", "status", "registered_by", "registered_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.connector:read" ] } ], "summary": "Search Connector", "tags": [ "connectors" ] } }, "/v1/object-types/hospitality.connector_sync_run/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne audited extraction/load run of a connector: what triggered it, when it ran, how many records were pulled from the source, landed in staging, and rejected by ontology validation at the map/load hop. Run-grain only — per-record state stays in the raw staging schema. The rejected count is customer-facing by design: 'your POS sent 14 rows the ontology refused' is part of the trust story (0037 §8).", "operationId": "get_hospitality_connector_sync_run", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector_sync_run" }, "properties": { "additionalProperties": false, "properties": { "cursor_window": { "title": "Per-stream cursor window this run covered (summary; live cursors live in staging)" }, "error_summary": { "title": "Terminal failure summary (required when status = failed)", "type": "string" }, "finished_at": { "format": "date-time", "title": "When the run reached a terminal status", "type": "string" }, "id": { "title": "Sync run id", "type": "string" }, "mapping_ref": { "title": "Mapping definition version used (defaults to the connector's at start)", "type": "string" }, "records_landed": { "title": "Records upserted into raw staging", "type": "integer" }, "records_pulled": { "title": "Records extracted from the source system", "type": "integer" }, "records_rejected": { "title": "Records refused by ontology validation at the map/load hop", "type": "integer" }, "started_at": { "format": "date-time", "title": "When the run started", "type": "string" }, "status": { "enum": [ "running", "succeeded", "failed", "cancelled" ], "title": "Sync-run lifecycle status", "type": "string" }, "streams": { "items": { "type": "string" }, "title": "Source streams this run pulled (vendor vocabulary)", "type": "array" }, "trigger": { "enum": [ "scheduled", "manual", "backfill" ], "title": "What initiated this run", "type": "string" } }, "required": [ "id", "status", "trigger", "started_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.connector_sync_run:read" ] } ], "summary": "Read Connector sync run", "tags": [ "connectors" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.connector_sync_run/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne audited extraction/load run of a connector: what triggered it, when it ran, how many records were pulled from the source, landed in staging, and rejected by ontology validation at the map/load hop. Run-grain only — per-record state stays in the raw staging schema. The rejected count is customer-facing by design: 'your POS sent 14 rows the ontology refused' is part of the trust story (0037 §8).", "operationId": "get_hospitality_connector_sync_run_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.connector_sync_run" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.connector_sync_run:read" ] } ], "summary": "Read Connector sync run as of a watermark", "tags": [ "connectors" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.connector_sync_run/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne audited extraction/load run of a connector: what triggered it, when it ran, how many records were pulled from the source, landed in staging, and rejected by ontology validation at the map/load hop. Run-grain only — per-record state stays in the raw staging schema. The rejected count is customer-facing by design: 'your POS sent 14 rows the ontology refused' is part of the trust story (0037 §8).", "operationId": "list_links_hospitality_connector_sync_run", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.connector_sync_run:read" ] } ], "summary": "List links of Connector sync run", "tags": [ "connectors" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.sync_run_for_connector" ] } } ] }, "/v1/object-types/hospitality.connector_sync_run/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne audited extraction/load run of a connector: what triggered it, when it ran, how many records were pulled from the source, landed in staging, and rejected by ontology validation at the map/load hop. Run-grain only — per-record state stays in the raw staging schema. The rejected count is customer-facing by design: 'your POS sent 14 rows the ontology refused' is part of the trust story (0037 §8).", "operationId": "traverse_hospitality_connector_sync_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.sync_run_for_connector" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.connector_sync_run:read" ] } ], "summary": "Traverse from Connector sync run", "tags": [ "connectors" ] } }, "/v1/object-types/hospitality.connector_sync_run/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne audited extraction/load run of a connector: what triggered it, when it ran, how many records were pulled from the source, landed in staging, and rejected by ontology validation at the map/load hop. Run-grain only — per-record state stays in the raw staging schema. The rejected count is customer-facing by design: 'your POS sent 14 rows the ontology refused' is part of the trust story (0037 §8).", "operationId": "search_hospitality_connector_sync_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "running", "succeeded", "failed", "cancelled" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "trigger" }, "type": { "const": "eq" }, "value": { "enum": [ "scheduled", "manual", "backfill" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "finished_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "finished_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "finished_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "streams" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "mapping_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "mapping_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "mapping_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "mapping_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "records_pulled" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "records_pulled" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "records_pulled" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "records_landed" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "records_landed" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "records_landed" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "records_rejected" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "records_rejected" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "records_rejected" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "error_summary" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "error_summary" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cursor_window" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "status", "trigger", "started_at", "finished_at", "mapping_ref", "records_pulled", "records_landed", "records_rejected", "error_summary" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.connector_sync_run" }, "properties": { "additionalProperties": false, "properties": { "cursor_window": { "title": "Per-stream cursor window this run covered (summary; live cursors live in staging)" }, "error_summary": { "title": "Terminal failure summary (required when status = failed)", "type": "string" }, "finished_at": { "format": "date-time", "title": "When the run reached a terminal status", "type": "string" }, "id": { "title": "Sync run id", "type": "string" }, "mapping_ref": { "title": "Mapping definition version used (defaults to the connector's at start)", "type": "string" }, "records_landed": { "title": "Records upserted into raw staging", "type": "integer" }, "records_pulled": { "title": "Records extracted from the source system", "type": "integer" }, "records_rejected": { "title": "Records refused by ontology validation at the map/load hop", "type": "integer" }, "started_at": { "format": "date-time", "title": "When the run started", "type": "string" }, "status": { "enum": [ "running", "succeeded", "failed", "cancelled" ], "title": "Sync-run lifecycle status", "type": "string" }, "streams": { "items": { "type": "string" }, "title": "Source streams this run pulled (vendor vocabulary)", "type": "array" }, "trigger": { "enum": [ "scheduled", "manual", "backfill" ], "title": "What initiated this run", "type": "string" } }, "required": [ "id", "status", "trigger", "started_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.connector_sync_run:read" ] } ], "summary": "Search Connector sync run", "tags": [ "connectors" ] } }, "/v1/object-types/hospitality.consent_policy/objects/{id}": { "get": { "description": "Read an existing instance.\n\nTenant-scoped, versioned consent policy. Authorises the `ConsentScope` envelopes embedded on objects and events: its `default_scope` is the deny-by-omission grant applied to any object without its own scope, `purposes_grantable` bounds what a scope may grant, and `min_cohort_size` is the kernel-level k-anonymity floor enforced on derived inference outputs. Versioned per the monotonic-version contract; `verified_by` records DPO sign-off.", "operationId": "get_hospitality_consent_policy", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.consent_policy" }, "properties": { "additionalProperties": false, "properties": { "authored_by": { "title": "Principal::stable_id() of the author", "type": "string" }, "default_scope": { "title": "Default `ConsentScope` applied to objects without their own scope" }, "effective_from": { "format": "date-time", "title": "When this policy version takes effect", "type": "string" }, "effective_until": { "format": "date-time", "title": "When this policy version is superseded", "type": "string" }, "id": { "title": "Policy id", "type": "string" }, "min_cohort_size": { "title": "Kernel-level k-anonymity floor (AWS Clean Rooms default: 5)", "type": "integer" }, "policy_text_uri": { "title": "Opaque pointer to the human-readable policy document", "type": "string" }, "purposes_grantable": { "items": { "enum": [ "operational", "benchmark_aggregate", "federated_query", "federated_training", "model_distillation", "fraud_network" ], "type": "string" }, "title": "The purposes this policy is permitted to grant", "type": "array" }, "regulatory_basis": { "title": "Regulatory regime this policy is written under (GDPR / CCPA / UK DUA …)", "type": "string" }, "verified_by": { "title": "Principal::stable_id() of the DPO sign-off, when verified", "type": "string" }, "version": { "title": "Monotonic policy version (a new grant strictly increases it)", "type": "integer" } }, "required": [ "id", "version", "default_scope", "purposes_grantable", "min_cohort_size", "effective_from", "authored_by", "regulatory_basis" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.consent_policy:read" ] } ], "summary": "Read Consent policy", "tags": [ "consent" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.consent_policy/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nTenant-scoped, versioned consent policy. Authorises the `ConsentScope` envelopes embedded on objects and events: its `default_scope` is the deny-by-omission grant applied to any object without its own scope, `purposes_grantable` bounds what a scope may grant, and `min_cohort_size` is the kernel-level k-anonymity floor enforced on derived inference outputs. Versioned per the monotonic-version contract; `verified_by` records DPO sign-off.", "operationId": "get_hospitality_consent_policy_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.consent_policy" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.consent_policy:read" ] } ], "summary": "Read Consent policy as of a watermark", "tags": [ "consent" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.consent_policy/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nTenant-scoped, versioned consent policy. Authorises the `ConsentScope` envelopes embedded on objects and events: its `default_scope` is the deny-by-omission grant applied to any object without its own scope, `purposes_grantable` bounds what a scope may grant, and `min_cohort_size` is the kernel-level k-anonymity floor enforced on derived inference outputs. Versioned per the monotonic-version contract; `verified_by` records DPO sign-off.", "operationId": "search_hospitality_consent_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "version" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "version" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "version" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "default_scope" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "purposes_grantable" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "operational", "benchmark_aggregate", "federated_query", "federated_training", "model_distillation", "fraud_network" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "min_cohort_size" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "min_cohort_size" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "min_cohort_size" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_until" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_until" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_until" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authored_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authored_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authored_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authored_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "verified_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "verified_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "verified_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "verified_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "policy_text_uri" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "policy_text_uri" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "policy_text_uri" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "policy_text_uri" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "regulatory_basis" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "regulatory_basis" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "regulatory_basis" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "regulatory_basis" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "version", "min_cohort_size", "effective_from", "effective_until", "authored_by", "verified_by", "policy_text_uri", "regulatory_basis" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.consent_policy" }, "properties": { "additionalProperties": false, "properties": { "authored_by": { "title": "Principal::stable_id() of the author", "type": "string" }, "default_scope": { "title": "Default `ConsentScope` applied to objects without their own scope" }, "effective_from": { "format": "date-time", "title": "When this policy version takes effect", "type": "string" }, "effective_until": { "format": "date-time", "title": "When this policy version is superseded", "type": "string" }, "id": { "title": "Policy id", "type": "string" }, "min_cohort_size": { "title": "Kernel-level k-anonymity floor (AWS Clean Rooms default: 5)", "type": "integer" }, "policy_text_uri": { "title": "Opaque pointer to the human-readable policy document", "type": "string" }, "purposes_grantable": { "items": { "enum": [ "operational", "benchmark_aggregate", "federated_query", "federated_training", "model_distillation", "fraud_network" ], "type": "string" }, "title": "The purposes this policy is permitted to grant", "type": "array" }, "regulatory_basis": { "title": "Regulatory regime this policy is written under (GDPR / CCPA / UK DUA …)", "type": "string" }, "verified_by": { "title": "Principal::stable_id() of the DPO sign-off, when verified", "type": "string" }, "version": { "title": "Monotonic policy version (a new grant strictly increases it)", "type": "integer" } }, "required": [ "id", "version", "default_scope", "purposes_grantable", "min_cohort_size", "effective_from", "authored_by", "regulatory_basis" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.consent_policy:read" ] } ], "summary": "Search Consent policy", "tags": [ "consent" ] } }, "/v1/object-types/hospitality.currency_conversion_rate/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA tenant-authored, effective-dated FX rate for converting amounts from one currency to another (units of to_currency per 1 from_currency). Consumers use the latest effective_from at or before the transaction date for the exact directed pair; inverse rates are never derived.", "operationId": "get_hospitality_currency_conversion_rate", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.currency_conversion_rate" }, "properties": { "additionalProperties": false, "properties": { "effective_from": { "format": "date", "title": "First business date this rate applies to", "type": "string" }, "from_currency": { "format": "iso-4217", "title": "Currency being converted from", "type": "string" }, "id": { "title": "Rate row id", "type": "string" }, "rate": { "format": "decimal", "title": "Units of to_currency per 1 from_currency; must be positive", "type": "string" }, "source_note": { "title": "Where the rate came from (treasury feed reference, manual note)", "type": "string" }, "to_currency": { "format": "iso-4217", "title": "Currency being converted to", "type": "string" } }, "required": [ "id", "from_currency", "to_currency", "rate", "effective_from" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.currency_conversion_rate:read" ] } ], "summary": "Read Currency conversion rate", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.currency_conversion_rate/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA tenant-authored, effective-dated FX rate for converting amounts from one currency to another (units of to_currency per 1 from_currency). Consumers use the latest effective_from at or before the transaction date for the exact directed pair; inverse rates are never derived.", "operationId": "get_hospitality_currency_conversion_rate_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.currency_conversion_rate" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.currency_conversion_rate:read" ] } ], "summary": "Read Currency conversion rate as of a watermark", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.currency_conversion_rate/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA tenant-authored, effective-dated FX rate for converting amounts from one currency to another (units of to_currency per 1 from_currency). Consumers use the latest effective_from at or before the transaction date for the exact directed pair; inverse rates are never derived.", "operationId": "search_hospitality_currency_conversion_rate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "from_currency" }, "type": { "const": "eq" }, "value": { "format": "iso-4217", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "to_currency" }, "type": { "const": "eq" }, "value": { "format": "iso-4217", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rate" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rate" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rate" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source_note" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source_note" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source_note" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source_note" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "rate", "effective_from", "source_note" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.currency_conversion_rate" }, "properties": { "additionalProperties": false, "properties": { "effective_from": { "format": "date", "title": "First business date this rate applies to", "type": "string" }, "from_currency": { "format": "iso-4217", "title": "Currency being converted from", "type": "string" }, "id": { "title": "Rate row id", "type": "string" }, "rate": { "format": "decimal", "title": "Units of to_currency per 1 from_currency; must be positive", "type": "string" }, "source_note": { "title": "Where the rate came from (treasury feed reference, manual note)", "type": "string" }, "to_currency": { "format": "iso-4217", "title": "Currency being converted to", "type": "string" } }, "required": [ "id", "from_currency", "to_currency", "rate", "effective_from" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.currency_conversion_rate:read" ] } ], "summary": "Search Currency conversion rate", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.demand_forecast/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne demand-forecast point: for a property and an arrival night, as of an instant, the rooms and ADR a segment is expected to realise, and — when the forecaster estimated it — the unconstrained demand behind them (`demand_rooms`, which may exceed capacity) and the rooms on the books when the forecast was made. Immutable: a re-forecast is a new point. Every point recorded feeds `forecast_point`, so the night-audit realization sweep grades it against the actual once the night has matured.", "operationId": "get_hospitality_demand_forecast", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.demand_forecast" }, "properties": { "additionalProperties": false, "properties": { "arrival_date": { "format": "date", "title": "The arrival night forecast", "type": "string" }, "demand_rooms": { "format": "decimal", "title": "Unconstrained demand in rooms, when estimated (may exceed capacity)", "type": "string" }, "external_ref": { "title": "Replay key for the forecasting source (unique per tenant while present)", "type": "string" }, "forecast_adr": { "description": "Average daily rate expected on the night", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Demand forecast forecast adr", "type": "object" }, "forecast_as_of": { "format": "date-time", "title": "When the forecast was made (business time)", "type": "string" }, "forecast_rooms": { "title": "Rooms expected to be sold on the night", "type": "integer" }, "id": { "title": "Forecast point id", "type": "string" }, "notes": { "title": "How the forecast was made", "type": "string" }, "on_the_books": { "title": "Rooms already on the books for the night when the forecast was made", "type": "integer" }, "segment": { "enum": [ "total", "transient", "group", "contract" ], "title": "Market segment forecast, or `total` for the house as a whole", "type": "string" }, "source": { "enum": [ "desk", "rms", "import" ], "title": "Who produced the forecast", "type": "string" } }, "required": [ "id", "forecast_as_of", "arrival_date", "segment", "source", "forecast_rooms", "forecast_adr" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.demand_forecast:read" ] } ], "summary": "Read Demand forecast", "tags": [ "revenue_management" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.demand_forecast/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne demand-forecast point: for a property and an arrival night, as of an instant, the rooms and ADR a segment is expected to realise, and — when the forecaster estimated it — the unconstrained demand behind them (`demand_rooms`, which may exceed capacity) and the rooms on the books when the forecast was made. Immutable: a re-forecast is a new point. Every point recorded feeds `forecast_point`, so the night-audit realization sweep grades it against the actual once the night has matured.", "operationId": "get_hospitality_demand_forecast_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.demand_forecast" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.demand_forecast:read" ] } ], "summary": "Read Demand forecast as of a watermark", "tags": [ "revenue_management" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.demand_forecast/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne demand-forecast point: for a property and an arrival night, as of an instant, the rooms and ADR a segment is expected to realise, and — when the forecaster estimated it — the unconstrained demand behind them (`demand_rooms`, which may exceed capacity) and the rooms on the books when the forecast was made. Immutable: a re-forecast is a new point. Every point recorded feeds `forecast_point`, so the night-audit realization sweep grades it against the actual once the night has matured.", "operationId": "list_links_hospitality_demand_forecast", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.demand_forecast:read" ] } ], "summary": "List links of Demand forecast", "tags": [ "revenue_management" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.demand_forecast_for_property" ] } } ] }, "/v1/object-types/hospitality.demand_forecast/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne demand-forecast point: for a property and an arrival night, as of an instant, the rooms and ADR a segment is expected to realise, and — when the forecaster estimated it — the unconstrained demand behind them (`demand_rooms`, which may exceed capacity) and the rooms on the books when the forecast was made. Immutable: a re-forecast is a new point. Every point recorded feeds `forecast_point`, so the night-audit realization sweep grades it against the actual once the night has matured.", "operationId": "traverse_hospitality_demand_forecast", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.demand_forecast_for_property" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.demand_forecast:read" ] } ], "summary": "Traverse from Demand forecast", "tags": [ "revenue_management" ] } }, "/v1/object-types/hospitality.demand_forecast/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne demand-forecast point: for a property and an arrival night, as of an instant, the rooms and ADR a segment is expected to realise, and — when the forecaster estimated it — the unconstrained demand behind them (`demand_rooms`, which may exceed capacity) and the rooms on the books when the forecast was made. Immutable: a re-forecast is a new point. Every point recorded feeds `forecast_point`, so the night-audit realization sweep grades it against the actual once the night has matured.", "operationId": "search_hospitality_demand_forecast", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "forecast_as_of" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "forecast_as_of" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "forecast_as_of" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "arrival_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "arrival_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "arrival_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "segment" }, "type": { "const": "eq" }, "value": { "enum": [ "total", "transient", "group", "contract" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source" }, "type": { "const": "eq" }, "value": { "enum": [ "desk", "rms", "import" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "forecast_rooms" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "forecast_rooms" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "forecast_rooms" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "forecast_adr" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "demand_rooms" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "demand_rooms" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "demand_rooms" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "on_the_books" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "on_the_books" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "on_the_books" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "forecast_as_of", "arrival_date", "segment", "source", "forecast_rooms", "demand_rooms", "on_the_books", "notes", "external_ref" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.demand_forecast" }, "properties": { "additionalProperties": false, "properties": { "arrival_date": { "format": "date", "title": "The arrival night forecast", "type": "string" }, "demand_rooms": { "format": "decimal", "title": "Unconstrained demand in rooms, when estimated (may exceed capacity)", "type": "string" }, "external_ref": { "title": "Replay key for the forecasting source (unique per tenant while present)", "type": "string" }, "forecast_adr": { "description": "Average daily rate expected on the night", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Demand forecast forecast adr", "type": "object" }, "forecast_as_of": { "format": "date-time", "title": "When the forecast was made (business time)", "type": "string" }, "forecast_rooms": { "title": "Rooms expected to be sold on the night", "type": "integer" }, "id": { "title": "Forecast point id", "type": "string" }, "notes": { "title": "How the forecast was made", "type": "string" }, "on_the_books": { "title": "Rooms already on the books for the night when the forecast was made", "type": "integer" }, "segment": { "enum": [ "total", "transient", "group", "contract" ], "title": "Market segment forecast, or `total` for the house as a whole", "type": "string" }, "source": { "enum": [ "desk", "rms", "import" ], "title": "Who produced the forecast", "type": "string" } }, "required": [ "id", "forecast_as_of", "arrival_date", "segment", "source", "forecast_rooms", "forecast_adr" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.demand_forecast:read" ] } ], "summary": "Search Demand forecast", "tags": [ "revenue_management" ] } }, "/v1/object-types/hospitality.deposit_policy/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne property-authored deposit rule: how much of the stay is due as an advance deposit (flat / percent of stay / percent of first night / nights), when it falls due (days after booking or days before arrival), whether an unpaid deposit auto-cancels the reservation at End of Day, and an effective-date window. Reservation creation derives `deposit_required_amount` / `deposit_due_at` from the rule active on the booking date and freezes the ref; rules sharing a `code` form a non-overlapping succession timeline.", "operationId": "get_hospitality_deposit_policy", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.deposit_policy" }, "properties": { "additionalProperties": false, "properties": { "auto_cancel_on_lapse": { "title": "Whether the night audit cancels a reservation whose deposit is still unpaid past the due date (OPERA's reservation-type auto-cancel flag). When false the sweep records the lapse and leaves the booking for the operator", "type": "boolean" }, "basis": { "enum": [ "flat", "percent_of_stay", "percent_of_first_night", "nights" ], "title": "How the required deposit computes", "type": "string" }, "code": { "title": "Policy code — the rule's identity within the property; rules sharing a code form one succession timeline", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "due_basis": { "enum": [ "days_after_booking", "days_before_arrival" ], "title": "Which anchor the due date is measured from", "type": "string" }, "due_days": { "title": "Day offset from the due anchor (>= 0)", "type": "integer" }, "effective_from": { "format": "date", "title": "First booking date the rule applies (inclusive)", "type": "string" }, "effective_to": { "format": "date", "title": "Last booking date the rule applies (inclusive); absent = open-ended", "type": "string" }, "flat_amount": { "description": "Amount for the `flat` basis. Required on flat, forbidden otherwise", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Deposit policy flat amount", "type": "object" }, "id": { "title": "Deposit policy id", "type": "string" }, "nights": { "title": "Night count for the `nights` basis (deposit = that many nights at the quoted rate). Required on nights, forbidden otherwise", "type": "integer" }, "rate": { "format": "decimal", "title": "Rate for the percent bases (decimal in [0, 1]; 0.50 = 50%). Required on percent bases, forbidden otherwise", "type": "string" } }, "required": [ "id", "code", "basis", "due_basis", "due_days", "auto_cancel_on_lapse", "effective_from" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.deposit_policy:read" ] } ], "summary": "Read Deposit policy", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.deposit_policy/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne property-authored deposit rule: how much of the stay is due as an advance deposit (flat / percent of stay / percent of first night / nights), when it falls due (days after booking or days before arrival), whether an unpaid deposit auto-cancels the reservation at End of Day, and an effective-date window. Reservation creation derives `deposit_required_amount` / `deposit_due_at` from the rule active on the booking date and freezes the ref; rules sharing a `code` form a non-overlapping succession timeline.", "operationId": "get_hospitality_deposit_policy_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.deposit_policy" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.deposit_policy:read" ] } ], "summary": "Read Deposit policy as of a watermark", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.deposit_policy/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne property-authored deposit rule: how much of the stay is due as an advance deposit (flat / percent of stay / percent of first night / nights), when it falls due (days after booking or days before arrival), whether an unpaid deposit auto-cancels the reservation at End of Day, and an effective-date window. Reservation creation derives `deposit_required_amount` / `deposit_due_at` from the rule active on the booking date and freezes the ref; rules sharing a `code` form a non-overlapping succession timeline.", "operationId": "list_links_hospitality_deposit_policy", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.deposit_policy:read" ] } ], "summary": "List links of Deposit policy", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.deposit_policy_at_property", "hospitality.link.rate_plan_requires_deposit_policy" ] } } ] }, "/v1/object-types/hospitality.deposit_policy/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne property-authored deposit rule: how much of the stay is due as an advance deposit (flat / percent of stay / percent of first night / nights), when it falls due (days after booking or days before arrival), whether an unpaid deposit auto-cancels the reservation at End of Day, and an effective-date window. Reservation creation derives `deposit_required_amount` / `deposit_due_at` from the rule active on the booking date and freezes the ref; rules sharing a `code` form a non-overlapping succession timeline.", "operationId": "traverse_hospitality_deposit_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.deposit_policy_at_property", "hospitality.link.rate_plan_requires_deposit_policy" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.deposit_policy:read" ] } ], "summary": "Traverse from Deposit policy", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.deposit_policy/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne property-authored deposit rule: how much of the stay is due as an advance deposit (flat / percent of stay / percent of first night / nights), when it falls due (days after booking or days before arrival), whether an unpaid deposit auto-cancels the reservation at End of Day, and an effective-date window. Reservation creation derives `deposit_required_amount` / `deposit_due_at` from the rule active on the booking date and freezes the ref; rules sharing a `code` form a non-overlapping succession timeline.", "operationId": "search_hospitality_deposit_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "basis" }, "type": { "const": "eq" }, "value": { "enum": [ "flat", "percent_of_stay", "percent_of_first_night", "nights" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rate" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rate" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rate" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "flat_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "nights" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "nights" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "nights" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "due_basis" }, "type": { "const": "eq" }, "value": { "enum": [ "days_after_booking", "days_before_arrival" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "due_days" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "due_days" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "due_days" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "auto_cancel_on_lapse" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "code", "basis", "rate", "nights", "due_basis", "due_days", "effective_from", "effective_to", "description" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.deposit_policy" }, "properties": { "additionalProperties": false, "properties": { "auto_cancel_on_lapse": { "title": "Whether the night audit cancels a reservation whose deposit is still unpaid past the due date (OPERA's reservation-type auto-cancel flag). When false the sweep records the lapse and leaves the booking for the operator", "type": "boolean" }, "basis": { "enum": [ "flat", "percent_of_stay", "percent_of_first_night", "nights" ], "title": "How the required deposit computes", "type": "string" }, "code": { "title": "Policy code — the rule's identity within the property; rules sharing a code form one succession timeline", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "due_basis": { "enum": [ "days_after_booking", "days_before_arrival" ], "title": "Which anchor the due date is measured from", "type": "string" }, "due_days": { "title": "Day offset from the due anchor (>= 0)", "type": "integer" }, "effective_from": { "format": "date", "title": "First booking date the rule applies (inclusive)", "type": "string" }, "effective_to": { "format": "date", "title": "Last booking date the rule applies (inclusive); absent = open-ended", "type": "string" }, "flat_amount": { "description": "Amount for the `flat` basis. Required on flat, forbidden otherwise", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Deposit policy flat amount", "type": "object" }, "id": { "title": "Deposit policy id", "type": "string" }, "nights": { "title": "Night count for the `nights` basis (deposit = that many nights at the quoted rate). Required on nights, forbidden otherwise", "type": "integer" }, "rate": { "format": "decimal", "title": "Rate for the percent bases (decimal in [0, 1]; 0.50 = 50%). Required on percent bases, forbidden otherwise", "type": "string" } }, "required": [ "id", "code", "basis", "due_basis", "due_days", "auto_cancel_on_lapse", "effective_from" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.deposit_policy:read" ] } ], "summary": "Search Deposit policy", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.derived_rate/objects/{id}": { "get": { "description": "Read an existing instance.\n\nMaterialised rate computation snapshot. Resolves a rate_plan + rate_per_night BAR anchor + derivation into a concrete effective_rate at a moment in time. Immutable after write per design-spec §B.2 — supersedence is via a fresh row with `superseded_at` set on the prior row.", "operationId": "get_hospitality_derived_rate", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.derived_rate" }, "properties": { "additionalProperties": false, "properties": { "bar_anchor_amount_at_compute": { "description": "BAR anchor in effect at compute time (snapshot)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Derived rate bar anchor amount at compute", "type": "object" }, "business_date": { "format": "date", "title": "Business date", "type": "string" }, "derivation_shape": { "enum": [ "bar_percent", "bar_absolute", "open_pricing", "static_contract" ], "title": "Derivation shape at compute time", "type": "string" }, "effective_at": { "format": "date-time", "title": "When this snapshot was computed", "type": "string" }, "effective_rate": { "description": "Computed rate", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Derived rate effective rate", "type": "object" }, "id": { "title": "Derived rate id", "type": "string" }, "modifier_value": { "format": "decimal", "title": "Modifier applied to the anchor (multiplier or absolute delta)", "type": "string" }, "superseded_at": { "format": "date-time", "title": "Superseded by a later snapshot at", "type": "string" } }, "required": [ "id", "business_date", "effective_at", "derivation_shape" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.derived_rate:read" ] } ], "summary": "Read Derived rate", "tags": [ "distribution" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.derived_rate/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nMaterialised rate computation snapshot. Resolves a rate_plan + rate_per_night BAR anchor + derivation into a concrete effective_rate at a moment in time. Immutable after write per design-spec §B.2 — supersedence is via a fresh row with `superseded_at` set on the prior row.", "operationId": "get_hospitality_derived_rate_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.derived_rate" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.derived_rate:read" ] } ], "summary": "Read Derived rate as of a watermark", "tags": [ "distribution" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.derived_rate/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nMaterialised rate computation snapshot. Resolves a rate_plan + rate_per_night BAR anchor + derivation into a concrete effective_rate at a moment in time. Immutable after write per design-spec §B.2 — supersedence is via a fresh row with `superseded_at` set on the prior row.", "operationId": "list_links_hospitality_derived_rate", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.derived_rate:read" ] } ], "summary": "List links of Derived rate", "tags": [ "distribution" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.derived_rate_for_rate_per_night", "hospitality.link.derived_rate_for_rate_plan", "hospitality.link.derived_rate_for_room_type" ] } } ] }, "/v1/object-types/hospitality.derived_rate/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nMaterialised rate computation snapshot. Resolves a rate_plan + rate_per_night BAR anchor + derivation into a concrete effective_rate at a moment in time. Immutable after write per design-spec §B.2 — supersedence is via a fresh row with `superseded_at` set on the prior row.", "operationId": "traverse_hospitality_derived_rate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.derived_rate_for_rate_per_night", "hospitality.link.derived_rate_for_rate_plan", "hospitality.link.derived_rate_for_room_type" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.derived_rate:read" ] } ], "summary": "Traverse from Derived rate", "tags": [ "distribution" ] } }, "/v1/object-types/hospitality.derived_rate/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nMaterialised rate computation snapshot. Resolves a rate_plan + rate_per_night BAR anchor + derivation into a concrete effective_rate at a moment in time. Immutable after write per design-spec §B.2 — supersedence is via a fresh row with `superseded_at` set on the prior row.", "operationId": "search_hospitality_derived_rate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_rate" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "bar_anchor_amount_at_compute" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "derivation_shape" }, "type": { "const": "eq" }, "value": { "enum": [ "bar_percent", "bar_absolute", "open_pricing", "static_contract" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "modifier_value" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "modifier_value" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "modifier_value" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "superseded_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "superseded_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "superseded_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "business_date", "effective_at", "derivation_shape", "modifier_value", "superseded_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.derived_rate" }, "properties": { "additionalProperties": false, "properties": { "bar_anchor_amount_at_compute": { "description": "BAR anchor in effect at compute time (snapshot)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Derived rate bar anchor amount at compute", "type": "object" }, "business_date": { "format": "date", "title": "Business date", "type": "string" }, "derivation_shape": { "enum": [ "bar_percent", "bar_absolute", "open_pricing", "static_contract" ], "title": "Derivation shape at compute time", "type": "string" }, "effective_at": { "format": "date-time", "title": "When this snapshot was computed", "type": "string" }, "effective_rate": { "description": "Computed rate", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Derived rate effective rate", "type": "object" }, "id": { "title": "Derived rate id", "type": "string" }, "modifier_value": { "format": "decimal", "title": "Modifier applied to the anchor (multiplier or absolute delta)", "type": "string" }, "superseded_at": { "format": "date-time", "title": "Superseded by a later snapshot at", "type": "string" } }, "required": [ "id", "business_date", "effective_at", "derivation_shape" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.derived_rate:read" ] } ], "summary": "Search Derived rate", "tags": [ "distribution" ] } }, "/v1/object-types/hospitality.design_dna/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA visual / spatial / service-tonal identity that connects venue brands or properties — the Sydell hotel-as-curator aesthetic across NoMad / Ace / LINE; the Soho House material palette and lighting language across House restaurants and Cowshed retail. Reused via N:N links (`property_has_design_dna`) and N:1 from venue brand (`venue_brand_has_design_dna`).", "operationId": "get_hospitality_design_dna", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.design_dna" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Design DNA code", "type": "string" }, "creative_director": { "title": "Creative director", "type": "string" }, "description": { "title": "Description", "type": "string" }, "house_style_guide_url": { "title": "House style guide URL", "type": "string" }, "lead_designer_ref": { "format": "uuid", "title": "Lead designer / firm (typed reference to a `company` with `kind = designer`)", "type": "string", "x-aerandil-references": "hospitality.company" }, "material_palette": { "title": "Material palette", "type": "string" }, "name": { "title": "Design DNA name", "type": "string" }, "photography_direction": { "title": "Photography direction", "type": "string" }, "service_register_default": { "enum": [ "formal_warm", "crafted_theatre", "quick_warm", "discreet_professional", "focused_coaching", "other" ], "title": "Service register default (mirrors proposal 0002 SURFACE_REGISTERS)", "type": "string" }, "typography_family": { "title": "Typography family", "type": "string" } }, "required": [ "code", "name" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.design_dna:read" ] } ], "summary": "Read Design DNA", "tags": [ "brand_venue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.design_dna/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA visual / spatial / service-tonal identity that connects venue brands or properties — the Sydell hotel-as-curator aesthetic across NoMad / Ace / LINE; the Soho House material palette and lighting language across House restaurants and Cowshed retail. Reused via N:N links (`property_has_design_dna`) and N:1 from venue brand (`venue_brand_has_design_dna`).", "operationId": "get_hospitality_design_dna_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.design_dna" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.design_dna:read" ] } ], "summary": "Read Design DNA as of a watermark", "tags": [ "brand_venue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.design_dna/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA visual / spatial / service-tonal identity that connects venue brands or properties — the Sydell hotel-as-curator aesthetic across NoMad / Ace / LINE; the Soho House material palette and lighting language across House restaurants and Cowshed retail. Reused via N:N links (`property_has_design_dna`) and N:1 from venue brand (`venue_brand_has_design_dna`).", "operationId": "list_links_hospitality_design_dna", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.design_dna:read" ] } ], "summary": "List links of Design DNA", "tags": [ "brand_venue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.design_dna_designed_by_company", "hospitality.link.design_dna_has_signature_scent", "hospitality.link.property_has_design_dna", "hospitality.link.venue_brand_has_design_dna" ] } } ] }, "/v1/object-types/hospitality.design_dna/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA visual / spatial / service-tonal identity that connects venue brands or properties — the Sydell hotel-as-curator aesthetic across NoMad / Ace / LINE; the Soho House material palette and lighting language across House restaurants and Cowshed retail. Reused via N:N links (`property_has_design_dna`) and N:1 from venue brand (`venue_brand_has_design_dna`).", "operationId": "traverse_hospitality_design_dna", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.design_dna_designed_by_company", "hospitality.link.design_dna_has_signature_scent", "hospitality.link.property_has_design_dna", "hospitality.link.venue_brand_has_design_dna" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.design_dna:read" ] } ], "summary": "Traverse from Design DNA", "tags": [ "brand_venue" ] } }, "/v1/object-types/hospitality.design_dna/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA visual / spatial / service-tonal identity that connects venue brands or properties — the Sydell hotel-as-curator aesthetic across NoMad / Ace / LINE; the Soho House material palette and lighting language across House restaurants and Cowshed retail. Reused via N:N links (`property_has_design_dna`) and N:1 from venue brand (`venue_brand_has_design_dna`).", "operationId": "search_hospitality_design_dna", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "material_palette" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "material_palette" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "typography_family" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "typography_family" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "photography_direction" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "photography_direction" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "service_register_default" }, "type": { "const": "eq" }, "value": { "enum": [ "formal_warm", "crafted_theatre", "quick_warm", "discreet_professional", "focused_coaching", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "lead_designer_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.company" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "creative_director" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "creative_director" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "creative_director" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "creative_director" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "house_style_guide_url" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "house_style_guide_url" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "house_style_guide_url" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "house_style_guide_url" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "material_palette", "typography_family", "photography_direction", "service_register_default", "creative_director", "house_style_guide_url", "description" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.design_dna" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Design DNA code", "type": "string" }, "creative_director": { "title": "Creative director", "type": "string" }, "description": { "title": "Description", "type": "string" }, "house_style_guide_url": { "title": "House style guide URL", "type": "string" }, "lead_designer_ref": { "format": "uuid", "title": "Lead designer / firm (typed reference to a `company` with `kind = designer`)", "type": "string", "x-aerandil-references": "hospitality.company" }, "material_palette": { "title": "Material palette", "type": "string" }, "name": { "title": "Design DNA name", "type": "string" }, "photography_direction": { "title": "Photography direction", "type": "string" }, "service_register_default": { "enum": [ "formal_warm", "crafted_theatre", "quick_warm", "discreet_professional", "focused_coaching", "other" ], "title": "Service register default (mirrors proposal 0002 SURFACE_REGISTERS)", "type": "string" }, "typography_family": { "title": "Typography family", "type": "string" } }, "required": [ "code", "name" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.design_dna:read" ] } ], "summary": "Search Design DNA", "tags": [ "brand_venue" ] } }, "/v1/object-types/hospitality.desk_session/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne shift at the front desk: opened when a member of staff signs in through the identity provider, bound to the property they work at, and handed between that property's desk staff by passcode without signing out. Every hand-over (`desk_session.switched`) and every re-proof of a passcode before a sensitive verb (`desk_session.stepped_up`) is an event on it, under the acting person's own principal. Holds no credential: the bearer tokens are the kernel's, minted per person and bounded by `shift_ends_at`.", "operationId": "get_hospitality_desk_session", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.desk_session" }, "properties": { "additionalProperties": false, "properties": { "closed_at": { "format": "date-time", "title": "Closed at (UTC)", "type": "string" }, "hands_changed_at": { "format": "date-time", "title": "When the desk last changed hands — opened, or a colleague switched in. A step-up on the same person's session does not move it; bearers minted before it are superseded", "type": "string" }, "id": { "title": "Session reference", "type": "string" }, "last_proven_at": { "format": "date-time", "title": "When the person at the desk last re-proved their passcode", "type": "string" }, "opened_at": { "format": "date-time", "title": "Opened at (UTC)", "type": "string" }, "outlet_id": { "description": "Set when the session is a till at one of the property's outlets rather than the front desk: a till is held and handed on by the F&B floor's roles (server, F&B manager), the front desk by the front office's, never the one by the other. Absent = the front desk.", "format": "uuid", "title": "The outlet whose till the session is", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "shift_ends_at": { "format": "date-time", "title": "Shift ends at (UTC) — no token minted for the session outlives it", "type": "string" }, "status": { "enum": [ "open", "closed" ], "title": "Status", "type": "string" } }, "required": [ "id", "status", "opened_at", "shift_ends_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.desk_session:read" ] } ], "summary": "Read Desk session", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.desk_session/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne shift at the front desk: opened when a member of staff signs in through the identity provider, bound to the property they work at, and handed between that property's desk staff by passcode without signing out. Every hand-over (`desk_session.switched`) and every re-proof of a passcode before a sensitive verb (`desk_session.stepped_up`) is an event on it, under the acting person's own principal. Holds no credential: the bearer tokens are the kernel's, minted per person and bounded by `shift_ends_at`.", "operationId": "get_hospitality_desk_session_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.desk_session" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.desk_session:read" ] } ], "summary": "Read Desk session as of a watermark", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.desk_session/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne shift at the front desk: opened when a member of staff signs in through the identity provider, bound to the property they work at, and handed between that property's desk staff by passcode without signing out. Every hand-over (`desk_session.switched`) and every re-proof of a passcode before a sensitive verb (`desk_session.stepped_up`) is an event on it, under the acting person's own principal. Holds no credential: the bearer tokens are the kernel's, minted per person and bounded by `shift_ends_at`.", "operationId": "list_links_hospitality_desk_session", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.desk_session:read" ] } ], "summary": "List links of Desk session", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.desk_session_acting_staff", "hospitality.link.desk_session_at_property", "hospitality.link.desk_session_opened_by" ] } } ] }, "/v1/object-types/hospitality.desk_session/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne shift at the front desk: opened when a member of staff signs in through the identity provider, bound to the property they work at, and handed between that property's desk staff by passcode without signing out. Every hand-over (`desk_session.switched`) and every re-proof of a passcode before a sensitive verb (`desk_session.stepped_up`) is an event on it, under the acting person's own principal. Holds no credential: the bearer tokens are the kernel's, minted per person and bounded by `shift_ends_at`.", "operationId": "traverse_hospitality_desk_session", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.desk_session_acting_staff", "hospitality.link.desk_session_at_property", "hospitality.link.desk_session_opened_by" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.desk_session:read" ] } ], "summary": "Traverse from Desk session", "tags": [ "people" ] } }, "/v1/object-types/hospitality.desk_session/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne shift at the front desk: opened when a member of staff signs in through the identity provider, bound to the property they work at, and handed between that property's desk staff by passcode without signing out. Every hand-over (`desk_session.switched`) and every re-proof of a passcode before a sensitive verb (`desk_session.stepped_up`) is an event on it, under the acting person's own principal. Holds no credential: the bearer tokens are the kernel's, minted per person and bounded by `shift_ends_at`.", "operationId": "search_hospitality_desk_session", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "open", "closed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "shift_ends_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "shift_ends_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "shift_ends_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_proven_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_proven_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_proven_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hands_changed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hands_changed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hands_changed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "outlet_id" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.outlet" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "status", "opened_at", "shift_ends_at", "last_proven_at", "hands_changed_at", "closed_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.desk_session" }, "properties": { "additionalProperties": false, "properties": { "closed_at": { "format": "date-time", "title": "Closed at (UTC)", "type": "string" }, "hands_changed_at": { "format": "date-time", "title": "When the desk last changed hands — opened, or a colleague switched in. A step-up on the same person's session does not move it; bearers minted before it are superseded", "type": "string" }, "id": { "title": "Session reference", "type": "string" }, "last_proven_at": { "format": "date-time", "title": "When the person at the desk last re-proved their passcode", "type": "string" }, "opened_at": { "format": "date-time", "title": "Opened at (UTC)", "type": "string" }, "outlet_id": { "description": "Set when the session is a till at one of the property's outlets rather than the front desk: a till is held and handed on by the F&B floor's roles (server, F&B manager), the front desk by the front office's, never the one by the other. Absent = the front desk.", "format": "uuid", "title": "The outlet whose till the session is", "type": "string", "x-aerandil-references": "hospitality.outlet" }, "shift_ends_at": { "format": "date-time", "title": "Shift ends at (UTC) — no token minted for the session outlives it", "type": "string" }, "status": { "enum": [ "open", "closed" ], "title": "Status", "type": "string" } }, "required": [ "id", "status", "opened_at", "shift_ends_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.desk_session:read" ] } ], "summary": "Search Desk session", "tags": [ "people" ] } }, "/v1/object-types/hospitality.development_pathway_definition/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOperator-authored progression ladder for a discipline. `staff_member.pathway_stage_code` references a `code` from the matching definition's `stages` array.", "operationId": "get_hospitality_development_pathway_definition", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.development_pathway_definition" }, "properties": { "additionalProperties": false, "properties": { "discipline": { "enum": [ "front_office", "food_beverage", "culinary", "bar", "housekeeping", "engineering", "spa", "wellness_clinical", "wellness_coaching", "sales", "revenue", "management", "other" ], "title": "Discipline", "type": "string" }, "id": { "title": "Definition id", "type": "string" }, "stages": { "description": "Ordered pathway stages", "items": { "properties": { "code": { "type": "string" }, "display_name": { "type": "string" }, "expected_tenure_years_to_reach": { "format": "decimal", "type": "string" }, "required_certification_kind": { "enum": [ "food_safety_manager", "food_safety_handler", "allergen_awareness", "alcohol_service", "haccp", "sommelier", "wset", "first_aid", "cpr", "pool_lifeguard", "massage_therapy_license", "cosmetology_license", "fire_safety", "other" ], "type": "string" }, "sort_index": { "type": "integer" } }, "required": [ "code", "display_name", "sort_index" ], "type": "object" }, "title": "Development pathway definition stages", "type": "array" } }, "required": [ "id", "discipline", "stages" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.development_pathway_definition:read" ] } ], "summary": "Read Development pathway definition", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.development_pathway_definition/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOperator-authored progression ladder for a discipline. `staff_member.pathway_stage_code` references a `code` from the matching definition's `stages` array.", "operationId": "get_hospitality_development_pathway_definition_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.development_pathway_definition" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.development_pathway_definition:read" ] } ], "summary": "Read Development pathway definition as of a watermark", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.development_pathway_definition/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOperator-authored progression ladder for a discipline. `staff_member.pathway_stage_code` references a `code` from the matching definition's `stages` array.", "operationId": "list_links_hospitality_development_pathway_definition", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.development_pathway_definition:read" ] } ], "summary": "List links of Development pathway definition", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.development_pathway_definition_at_brand", "hospitality.link.development_pathway_definition_at_property" ] } } ] }, "/v1/object-types/hospitality.development_pathway_definition/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOperator-authored progression ladder for a discipline. `staff_member.pathway_stage_code` references a `code` from the matching definition's `stages` array.", "operationId": "traverse_hospitality_development_pathway_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.development_pathway_definition_at_brand", "hospitality.link.development_pathway_definition_at_property" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.development_pathway_definition:read" ] } ], "summary": "Traverse from Development pathway definition", "tags": [ "people" ] } }, "/v1/object-types/hospitality.development_pathway_definition/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOperator-authored progression ladder for a discipline. `staff_member.pathway_stage_code` references a `code` from the matching definition's `stages` array.", "operationId": "search_hospitality_development_pathway_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "discipline" }, "type": { "const": "eq" }, "value": { "enum": [ "front_office", "food_beverage", "culinary", "bar", "housekeeping", "engineering", "spa", "wellness_clinical", "wellness_coaching", "sales", "revenue", "management", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "stages" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "code": { "type": "string" }, "display_name": { "type": "string" }, "expected_tenure_years_to_reach": { "format": "decimal", "type": "string" }, "required_certification_kind": { "enum": [ "food_safety_manager", "food_safety_handler", "allergen_awareness", "alcohol_service", "haccp", "sommelier", "wset", "first_aid", "cpr", "pool_lifeguard", "massage_therapy_license", "cosmetology_license", "fire_safety", "other" ], "type": "string" }, "sort_index": { "type": "integer" } }, "required": [ "code", "display_name", "sort_index" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "discipline" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.development_pathway_definition" }, "properties": { "additionalProperties": false, "properties": { "discipline": { "enum": [ "front_office", "food_beverage", "culinary", "bar", "housekeeping", "engineering", "spa", "wellness_clinical", "wellness_coaching", "sales", "revenue", "management", "other" ], "title": "Discipline", "type": "string" }, "id": { "title": "Definition id", "type": "string" }, "stages": { "description": "Ordered pathway stages", "items": { "properties": { "code": { "type": "string" }, "display_name": { "type": "string" }, "expected_tenure_years_to_reach": { "format": "decimal", "type": "string" }, "required_certification_kind": { "enum": [ "food_safety_manager", "food_safety_handler", "allergen_awareness", "alcohol_service", "haccp", "sommelier", "wset", "first_aid", "cpr", "pool_lifeguard", "massage_therapy_license", "cosmetology_license", "fire_safety", "other" ], "type": "string" }, "sort_index": { "type": "integer" } }, "required": [ "code", "display_name", "sort_index" ], "type": "object" }, "title": "Development pathway definition stages", "type": "array" } }, "required": [ "id", "discipline", "stages" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.development_pathway_definition:read" ] } ], "summary": "Search Development pathway definition", "tags": [ "people" ] } }, "/v1/object-types/hospitality.device/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA registered piece of local hardware at a property — the attribution and authorisation anchor for writes that originate from a physical machine rather than a person. The first consumer is the charge-to-key surface: `post_charge_by_credential` requires an `active` payment-terminal device, so a tap from an unregistered reader fails closed. `kind` reserves vocabulary for the rest of the hardware estate (key encoders, door locks, kiosks, printers) so the abstraction doesn't churn per product.", "operationId": "get_hospitality_device", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.device" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Device code", "type": "string" }, "description": { "title": "Description", "type": "string" }, "kind": { "enum": [ "payment_terminal", "key_encoder", "door_lock", "kiosk", "printer", "handset", "other" ], "title": "Hardware kind", "type": "string" }, "name": { "title": "Device name", "type": "string" }, "print_secret_hash": { "description": "A printer's poll credential: the lowercase hex SHA-256 of the secret its Server Direct Print settings carry. Set by `register_device`; never readable.", "title": "Print secret hash (hex SHA-256)", "type": "string" }, "status": { "enum": [ "active", "inactive", "retired" ], "title": "Lifecycle status", "type": "string" }, "vendor": { "title": "Hardware / acquirer vendor (free text — vendor-specific)", "type": "string" }, "vendor_device_ref": { "title": "Vendor-side device identifier (free text — vendor-specific)", "type": "string" } }, "required": [ "code", "name", "kind", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.device:read" ] } ], "summary": "Read Device", "tags": [ "access" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.device/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA registered piece of local hardware at a property — the attribution and authorisation anchor for writes that originate from a physical machine rather than a person. The first consumer is the charge-to-key surface: `post_charge_by_credential` requires an `active` payment-terminal device, so a tap from an unregistered reader fails closed. `kind` reserves vocabulary for the rest of the hardware estate (key encoders, door locks, kiosks, printers) so the abstraction doesn't churn per product.", "operationId": "get_hospitality_device_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.device" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.device:read" ] } ], "summary": "Read Device as of a watermark", "tags": [ "access" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.device/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA registered piece of local hardware at a property — the attribution and authorisation anchor for writes that originate from a physical machine rather than a person. The first consumer is the charge-to-key surface: `post_charge_by_credential` requires an `active` payment-terminal device, so a tap from an unregistered reader fails closed. `kind` reserves vocabulary for the rest of the hardware estate (key encoders, door locks, kiosks, printers) so the abstraction doesn't churn per product.", "operationId": "list_links_hospitality_device", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.device:read" ] } ], "summary": "List links of Device", "tags": [ "access" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.device_at_outlet", "hospitality.link.device_at_property" ] } } ] }, "/v1/object-types/hospitality.device/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA registered piece of local hardware at a property — the attribution and authorisation anchor for writes that originate from a physical machine rather than a person. The first consumer is the charge-to-key surface: `post_charge_by_credential` requires an `active` payment-terminal device, so a tap from an unregistered reader fails closed. `kind` reserves vocabulary for the rest of the hardware estate (key encoders, door locks, kiosks, printers) so the abstraction doesn't churn per product.", "operationId": "traverse_hospitality_device", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.device_at_outlet", "hospitality.link.device_at_property" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.device:read" ] } ], "summary": "Traverse from Device", "tags": [ "access" ] } }, "/v1/object-types/hospitality.device/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA registered piece of local hardware at a property — the attribution and authorisation anchor for writes that originate from a physical machine rather than a person. The first consumer is the charge-to-key surface: `post_charge_by_credential` requires an `active` payment-terminal device, so a tap from an unregistered reader fails closed. `kind` reserves vocabulary for the rest of the hardware estate (key encoders, door locks, kiosks, printers) so the abstraction doesn't churn per product.", "operationId": "search_hospitality_device", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "payment_terminal", "key_encoder", "door_lock", "kiosk", "printer", "handset", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "inactive", "retired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor_device_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor_device_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor_device_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor_device_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "print_secret_hash" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "print_secret_hash" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "print_secret_hash" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "print_secret_hash" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "kind", "status", "vendor", "vendor_device_ref", "description", "print_secret_hash" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.device" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Device code", "type": "string" }, "description": { "title": "Description", "type": "string" }, "kind": { "enum": [ "payment_terminal", "key_encoder", "door_lock", "kiosk", "printer", "handset", "other" ], "title": "Hardware kind", "type": "string" }, "name": { "title": "Device name", "type": "string" }, "print_secret_hash": { "description": "A printer's poll credential: the lowercase hex SHA-256 of the secret its Server Direct Print settings carry. Set by `register_device`; never readable.", "title": "Print secret hash (hex SHA-256)", "type": "string" }, "status": { "enum": [ "active", "inactive", "retired" ], "title": "Lifecycle status", "type": "string" }, "vendor": { "title": "Hardware / acquirer vendor (free text — vendor-specific)", "type": "string" }, "vendor_device_ref": { "title": "Vendor-side device identifier (free text — vendor-specific)", "type": "string" } }, "required": [ "code", "name", "kind", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.device:read" ] } ], "summary": "Search Device", "tags": [ "access" ] } }, "/v1/object-types/hospitality.dispute_evidence_packet/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe evidence the kernel assembled to counter one chargeback: the text fields it would send, the documents it would attach (each pinned to the source object's id and version), and the evidence the argument wanted but the house could not supply. Built from what the kernel already holds — folio, frozen cancellation terms, stay record, 3DS outcome — so nobody at the property gathers or uploads anything. A person counters or accepts; the one submission the kernel makes itself is a packet with no gaps still unsent 48 hours before the deadline (move 13, 2026-10-22: the night audit's sweep, `submitted_by = system`).", "operationId": "get_hospitality_dispute_evidence_packet", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.dispute_evidence_packet" }, "properties": { "additionalProperties": false, "properties": { "assembled_at": { "format": "date-time", "title": "Assembled at", "type": "string" }, "byte_count": { "title": "The bytes the packet's documents came to when they were rendered for the processor (4.5 MB at most in all)", "type": "integer" }, "documents": { "description": "The files the packet attaches, one per evidence type, each naming the object and version it is rendered from", "items": { "properties": { "evidence_type": { "enum": [ "receipt", "service_documentation", "cancellation_policy", "customer_signature", "duplicate_charge_documentation", "customer_communication", "uncategorized_file" ], "type": "string" }, "source_id": { "type": "string" }, "source_object_type": { "type": "string" }, "source_version": { "type": "integer" }, "sources": { "items": { "properties": { "source_id": { "type": "string" }, "source_object_type": { "type": "string" }, "source_version": { "type": "integer" } }, "required": [ "source_object_type", "source_id", "source_version" ], "type": "object" }, "type": "array" } }, "required": [ "evidence_type", "source_object_type", "source_id", "source_version" ], "type": "object" }, "title": "Dispute evidence packet documents", "type": "array" }, "enhanced_evidence": { "description": "Visa Compelling Evidence 3.0, as the processor takes it (Stripe `evidence[enhanced_evidence][visa_compelling_evidence_3]`): the disputed booking's identifiers and two prior undisputed charges on the same card, 120 to 364 days before it, each matching the disputed one on two of the purchase IP, the device and the guest's email (at least one of them the IP or the device). Each prior names the payment and version it was read from, checked again before the packet is sent. Absent when the case is not Visa card-absent fraud, when the processor's own prior transactions already qualify, or when two were not found (a gap says how many were).", "properties": { "customer_device_id": { "type": "string" }, "customer_email_address": { "type": "string" }, "customer_purchase_ip": { "type": "string" }, "merchandise_or_services": { "type": "string" }, "priors": { "items": { "properties": { "captured_at": { "format": "date-time", "type": "string" }, "charge": { "type": "string" }, "customer_device_id": { "type": "string" }, "customer_email_address": { "type": "string" }, "customer_purchase_ip": { "type": "string" }, "matches": { "type": "integer" }, "payment_id": { "type": "string" }, "payment_version": { "type": "integer" }, "product_description": { "type": "string" } }, "required": [ "payment_id", "payment_version", "charge", "captured_at", "product_description", "matches" ], "type": "object" }, "type": "array" }, "product_description": { "type": "string" } }, "required": [ "merchandise_or_services", "product_description", "priors" ], "title": "Dispute evidence packet enhanced evidence", "type": "object" }, "fields": { "additionalProperties": true, "title": "The text evidence, keyed by the processor's evidence name (`customer_name`, `service_date`, `cancellation_policy_disclosure`, …). Generated from the objects, never written freehand, so every sentence can be checked against the packet's own sources.", "type": "object" }, "files": { "description": "The files uploaded for this packet, one per evidence type, as the processor's file ids — recorded when the packet is marked `sending`, before the dispute update", "items": { "properties": { "evidence_type": { "enum": [ "receipt", "service_documentation", "cancellation_policy", "customer_signature", "duplicate_charge_documentation", "customer_communication", "uncategorized_file" ], "type": "string" }, "file_id": { "type": "string" } }, "required": [ "evidence_type", "file_id" ], "type": "object" }, "title": "Dispute evidence packet files", "type": "array" }, "gaps": { "description": "Evidence the argument wanted and the kernel could not supply — shown to the desk before it counters, so a weak case is visible as one", "items": { "properties": { "evidence": { "type": "string" }, "why": { "type": "string" } }, "required": [ "evidence", "why" ], "type": "object" }, "title": "Dispute evidence packet gaps", "type": "array" }, "gaps_acknowledged": { "title": "Whether the house submitted knowing the packet's gaps — required when there are any", "type": "boolean" }, "gaps_acknowledged_by": { "title": "Who acknowledged the gaps and submitted (the principal)", "type": "string" }, "id": { "title": "Packet id", "type": "string" }, "packet_version": { "title": "1 for the first assembly on a case; each re-assembly bumps it and supersedes the unsent packet before it", "type": "integer" }, "page_count": { "title": "The pages the packet's documents came to when they were rendered for the processor — the networks' limit is counted on these (fewer than 50 in all; 19 for Mastercard)", "type": "integer" }, "refusal": { "title": "The processor's words when it refused this packet — a refused packet is not sent again; assembling another is the retry", "type": "string" }, "sending_at": { "format": "date-time", "title": "When the packet's dispute update was sent to the processor (its idempotency key is remembered for 24 hours from then)", "type": "string" }, "status": { "enum": [ "draft", "staged", "submitted", "accepted", "superseded", "sending", "superseded_by_escalation" ], "title": "Status", "type": "string" }, "submitted_at": { "format": "date-time", "title": "When the processor took the packet to the issuer", "type": "string" }, "submitted_by": { "title": "Who sent the packet to the processor: the principal, or `system` when the night audit's sweep submitted a gap-free packet 48 hours before the deadline", "type": "string" }, "template": { "enum": [ "fraud", "no_show", "cancellation", "duplicate", "service" ], "title": "Which argument the packet makes — chosen from the dispute reason and what happened to the booking. Recorded so a later change to the templates cannot rewrite what this packet said.", "type": "string" } }, "required": [ "id", "status", "template", "packet_version", "assembled_at", "documents", "gaps" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.dispute_evidence_packet:read" ] } ], "summary": "Read Dispute evidence packet", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.dispute_evidence_packet/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe evidence the kernel assembled to counter one chargeback: the text fields it would send, the documents it would attach (each pinned to the source object's id and version), and the evidence the argument wanted but the house could not supply. Built from what the kernel already holds — folio, frozen cancellation terms, stay record, 3DS outcome — so nobody at the property gathers or uploads anything. A person counters or accepts; the one submission the kernel makes itself is a packet with no gaps still unsent 48 hours before the deadline (move 13, 2026-10-22: the night audit's sweep, `submitted_by = system`).", "operationId": "get_hospitality_dispute_evidence_packet_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.dispute_evidence_packet" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.dispute_evidence_packet:read" ] } ], "summary": "Read Dispute evidence packet as of a watermark", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.dispute_evidence_packet/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe evidence the kernel assembled to counter one chargeback: the text fields it would send, the documents it would attach (each pinned to the source object's id and version), and the evidence the argument wanted but the house could not supply. Built from what the kernel already holds — folio, frozen cancellation terms, stay record, 3DS outcome — so nobody at the property gathers or uploads anything. A person counters or accepts; the one submission the kernel makes itself is a packet with no gaps still unsent 48 hours before the deadline (move 13, 2026-10-22: the night audit's sweep, `submitted_by = system`).", "operationId": "list_links_hospitality_dispute_evidence_packet", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.dispute_evidence_packet:read" ] } ], "summary": "List links of Dispute evidence packet", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.evidence_packet_for_dispute" ] } } ] }, "/v1/object-types/hospitality.dispute_evidence_packet/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe evidence the kernel assembled to counter one chargeback: the text fields it would send, the documents it would attach (each pinned to the source object's id and version), and the evidence the argument wanted but the house could not supply. Built from what the kernel already holds — folio, frozen cancellation terms, stay record, 3DS outcome — so nobody at the property gathers or uploads anything. A person counters or accepts; the one submission the kernel makes itself is a packet with no gaps still unsent 48 hours before the deadline (move 13, 2026-10-22: the night audit's sweep, `submitted_by = system`).", "operationId": "traverse_hospitality_dispute_evidence_packet", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.evidence_packet_for_dispute" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.dispute_evidence_packet:read" ] } ], "summary": "Traverse from Dispute evidence packet", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.dispute_evidence_packet/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe evidence the kernel assembled to counter one chargeback: the text fields it would send, the documents it would attach (each pinned to the source object's id and version), and the evidence the argument wanted but the house could not supply. Built from what the kernel already holds — folio, frozen cancellation terms, stay record, 3DS outcome — so nobody at the property gathers or uploads anything. A person counters or accepts; the one submission the kernel makes itself is a packet with no gaps still unsent 48 hours before the deadline (move 13, 2026-10-22: the night audit's sweep, `submitted_by = system`).", "operationId": "search_hospitality_dispute_evidence_packet", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "draft", "staged", "submitted", "accepted", "superseded", "sending", "superseded_by_escalation" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "template" }, "type": { "const": "eq" }, "value": { "enum": [ "fraud", "no_show", "cancellation", "duplicate", "service" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "packet_version" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "packet_version" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "packet_version" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "assembled_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "assembled_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "assembled_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fields" }, "type": { "const": "eq" }, "value": { "additionalProperties": true, "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "documents" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "evidence_type": { "enum": [ "receipt", "service_documentation", "cancellation_policy", "customer_signature", "duplicate_charge_documentation", "customer_communication", "uncategorized_file" ], "type": "string" }, "source_id": { "type": "string" }, "source_object_type": { "type": "string" }, "source_version": { "type": "integer" }, "sources": { "items": { "properties": { "source_id": { "type": "string" }, "source_object_type": { "type": "string" }, "source_version": { "type": "integer" } }, "required": [ "source_object_type", "source_id", "source_version" ], "type": "object" }, "type": "array" } }, "required": [ "evidence_type", "source_object_type", "source_id", "source_version" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "gaps" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "evidence": { "type": "string" }, "why": { "type": "string" } }, "required": [ "evidence", "why" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "submitted_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "submitted_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "submitted_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "gaps_acknowledged" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "gaps_acknowledged_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "gaps_acknowledged_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "gaps_acknowledged_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "gaps_acknowledged_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "submitted_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "submitted_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "submitted_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "submitted_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refusal" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refusal" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "files" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "evidence_type": { "enum": [ "receipt", "service_documentation", "cancellation_policy", "customer_signature", "duplicate_charge_documentation", "customer_communication", "uncategorized_file" ], "type": "string" }, "file_id": { "type": "string" } }, "required": [ "evidence_type", "file_id" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sending_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sending_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sending_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "enhanced_evidence" }, "type": { "const": "eq" }, "value": { "properties": { "customer_device_id": { "type": "string" }, "customer_email_address": { "type": "string" }, "customer_purchase_ip": { "type": "string" }, "merchandise_or_services": { "type": "string" }, "priors": { "items": { "properties": { "captured_at": { "format": "date-time", "type": "string" }, "charge": { "type": "string" }, "customer_device_id": { "type": "string" }, "customer_email_address": { "type": "string" }, "customer_purchase_ip": { "type": "string" }, "matches": { "type": "integer" }, "payment_id": { "type": "string" }, "payment_version": { "type": "integer" }, "product_description": { "type": "string" } }, "required": [ "payment_id", "payment_version", "charge", "captured_at", "product_description", "matches" ], "type": "object" }, "type": "array" }, "product_description": { "type": "string" } }, "required": [ "merchandise_or_services", "product_description", "priors" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "page_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "page_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "page_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "byte_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "byte_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "byte_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "status", "template", "packet_version", "assembled_at", "submitted_at", "gaps_acknowledged_by", "submitted_by", "refusal", "sending_at", "page_count", "byte_count" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.dispute_evidence_packet" }, "properties": { "additionalProperties": false, "properties": { "assembled_at": { "format": "date-time", "title": "Assembled at", "type": "string" }, "byte_count": { "title": "The bytes the packet's documents came to when they were rendered for the processor (4.5 MB at most in all)", "type": "integer" }, "documents": { "description": "The files the packet attaches, one per evidence type, each naming the object and version it is rendered from", "items": { "properties": { "evidence_type": { "enum": [ "receipt", "service_documentation", "cancellation_policy", "customer_signature", "duplicate_charge_documentation", "customer_communication", "uncategorized_file" ], "type": "string" }, "source_id": { "type": "string" }, "source_object_type": { "type": "string" }, "source_version": { "type": "integer" }, "sources": { "items": { "properties": { "source_id": { "type": "string" }, "source_object_type": { "type": "string" }, "source_version": { "type": "integer" } }, "required": [ "source_object_type", "source_id", "source_version" ], "type": "object" }, "type": "array" } }, "required": [ "evidence_type", "source_object_type", "source_id", "source_version" ], "type": "object" }, "title": "Dispute evidence packet documents", "type": "array" }, "enhanced_evidence": { "description": "Visa Compelling Evidence 3.0, as the processor takes it (Stripe `evidence[enhanced_evidence][visa_compelling_evidence_3]`): the disputed booking's identifiers and two prior undisputed charges on the same card, 120 to 364 days before it, each matching the disputed one on two of the purchase IP, the device and the guest's email (at least one of them the IP or the device). Each prior names the payment and version it was read from, checked again before the packet is sent. Absent when the case is not Visa card-absent fraud, when the processor's own prior transactions already qualify, or when two were not found (a gap says how many were).", "properties": { "customer_device_id": { "type": "string" }, "customer_email_address": { "type": "string" }, "customer_purchase_ip": { "type": "string" }, "merchandise_or_services": { "type": "string" }, "priors": { "items": { "properties": { "captured_at": { "format": "date-time", "type": "string" }, "charge": { "type": "string" }, "customer_device_id": { "type": "string" }, "customer_email_address": { "type": "string" }, "customer_purchase_ip": { "type": "string" }, "matches": { "type": "integer" }, "payment_id": { "type": "string" }, "payment_version": { "type": "integer" }, "product_description": { "type": "string" } }, "required": [ "payment_id", "payment_version", "charge", "captured_at", "product_description", "matches" ], "type": "object" }, "type": "array" }, "product_description": { "type": "string" } }, "required": [ "merchandise_or_services", "product_description", "priors" ], "title": "Dispute evidence packet enhanced evidence", "type": "object" }, "fields": { "additionalProperties": true, "title": "The text evidence, keyed by the processor's evidence name (`customer_name`, `service_date`, `cancellation_policy_disclosure`, …). Generated from the objects, never written freehand, so every sentence can be checked against the packet's own sources.", "type": "object" }, "files": { "description": "The files uploaded for this packet, one per evidence type, as the processor's file ids — recorded when the packet is marked `sending`, before the dispute update", "items": { "properties": { "evidence_type": { "enum": [ "receipt", "service_documentation", "cancellation_policy", "customer_signature", "duplicate_charge_documentation", "customer_communication", "uncategorized_file" ], "type": "string" }, "file_id": { "type": "string" } }, "required": [ "evidence_type", "file_id" ], "type": "object" }, "title": "Dispute evidence packet files", "type": "array" }, "gaps": { "description": "Evidence the argument wanted and the kernel could not supply — shown to the desk before it counters, so a weak case is visible as one", "items": { "properties": { "evidence": { "type": "string" }, "why": { "type": "string" } }, "required": [ "evidence", "why" ], "type": "object" }, "title": "Dispute evidence packet gaps", "type": "array" }, "gaps_acknowledged": { "title": "Whether the house submitted knowing the packet's gaps — required when there are any", "type": "boolean" }, "gaps_acknowledged_by": { "title": "Who acknowledged the gaps and submitted (the principal)", "type": "string" }, "id": { "title": "Packet id", "type": "string" }, "packet_version": { "title": "1 for the first assembly on a case; each re-assembly bumps it and supersedes the unsent packet before it", "type": "integer" }, "page_count": { "title": "The pages the packet's documents came to when they were rendered for the processor — the networks' limit is counted on these (fewer than 50 in all; 19 for Mastercard)", "type": "integer" }, "refusal": { "title": "The processor's words when it refused this packet — a refused packet is not sent again; assembling another is the retry", "type": "string" }, "sending_at": { "format": "date-time", "title": "When the packet's dispute update was sent to the processor (its idempotency key is remembered for 24 hours from then)", "type": "string" }, "status": { "enum": [ "draft", "staged", "submitted", "accepted", "superseded", "sending", "superseded_by_escalation" ], "title": "Status", "type": "string" }, "submitted_at": { "format": "date-time", "title": "When the processor took the packet to the issuer", "type": "string" }, "submitted_by": { "title": "Who sent the packet to the processor: the principal, or `system` when the night audit's sweep submitted a gap-free packet 48 hours before the deadline", "type": "string" }, "template": { "enum": [ "fraud", "no_show", "cancellation", "duplicate", "service" ], "title": "Which argument the packet makes — chosen from the dispute reason and what happened to the booking. Recorded so a later change to the templates cannot rewrite what this packet said.", "type": "string" } }, "required": [ "id", "status", "template", "packet_version", "assembled_at", "documents", "gaps" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.dispute_evidence_packet:read" ] } ], "summary": "Search Dispute evidence packet", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.erasure_request/objects/{id}": { "get": { "description": "Read an existing instance.\n\nDurable audit record for an Article 17 right-to-erasure demand: the target object, the requester, the reviewer's decision, and what the hard delete removed. Outlives the object it targets — the target row is erased, the compliance trail is not.", "operationId": "get_hospitality_erasure_request", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.erasure_request" }, "properties": { "additionalProperties": false, "properties": { "decided_at": { "format": "date-time", "title": "Decision recorded at", "type": "string" }, "decided_by": { "title": "Deciding principal", "type": "string" }, "decision_note": { "title": "Reviewer's note", "type": "string" }, "id": { "title": "Erasure-request id", "type": "string" }, "links_removed": { "title": "Links cascade-deleted at erasure", "type": "integer" }, "object_id": { "title": "Target object id", "type": "string" }, "object_type": { "title": "Target object type", "type": "string" }, "reason": { "title": "Request reason", "type": "string" }, "requested_by": { "title": "Requesting principal", "type": "string" }, "status": { "enum": [ "pending", "approved", "rejected" ], "title": "Lifecycle status", "type": "string" } }, "required": [ "id", "object_type", "object_id", "status", "requested_by" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.erasure_request:read" ] } ], "summary": "Read Erasure request", "tags": [ "erasure_requests" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.erasure_request/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nDurable audit record for an Article 17 right-to-erasure demand: the target object, the requester, the reviewer's decision, and what the hard delete removed. Outlives the object it targets — the target row is erased, the compliance trail is not.", "operationId": "get_hospitality_erasure_request_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.erasure_request" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.erasure_request:read" ] } ], "summary": "Read Erasure request as of a watermark", "tags": [ "erasure_requests" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.erasure_request/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nDurable audit record for an Article 17 right-to-erasure demand: the target object, the requester, the reviewer's decision, and what the hard delete removed. Outlives the object it targets — the target row is erased, the compliance trail is not.", "operationId": "search_hospitality_erasure_request", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "object_type" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "object_type" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "object_type" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "object_type" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "object_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "object_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "object_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "object_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "pending", "approved", "rejected" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decision_note" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decision_note" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "links_removed" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "links_removed" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "links_removed" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "object_type", "object_id", "status", "reason", "requested_by", "decided_by", "decision_note", "decided_at", "links_removed" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.erasure_request" }, "properties": { "additionalProperties": false, "properties": { "decided_at": { "format": "date-time", "title": "Decision recorded at", "type": "string" }, "decided_by": { "title": "Deciding principal", "type": "string" }, "decision_note": { "title": "Reviewer's note", "type": "string" }, "id": { "title": "Erasure-request id", "type": "string" }, "links_removed": { "title": "Links cascade-deleted at erasure", "type": "integer" }, "object_id": { "title": "Target object id", "type": "string" }, "object_type": { "title": "Target object type", "type": "string" }, "reason": { "title": "Request reason", "type": "string" }, "requested_by": { "title": "Requesting principal", "type": "string" }, "status": { "enum": [ "pending", "approved", "rejected" ], "title": "Lifecycle status", "type": "string" } }, "required": [ "id", "object_type", "object_id", "status", "requested_by" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.erasure_request:read" ] } ], "summary": "Search Erasure request", "tags": [ "erasure_requests" ] } }, "/v1/object-types/hospitality.external_consortium/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA soft-tier consortium (LHW, SLH, Preferred, Relais & Châteaux, Virtuoso) — properties opt in via the `loyalty_program_for_consortium` link. The consortium runs its own central operations and member identity; the loyalty_program at the property level points back here. Tenant-scoped because the consortium is a tenant-wide entity from Aerandil's perspective; cross-tenant canonicalisation (two Aerandil tenants both running LHW Leaders Club from the same consortium identity) defers per design-spec §G loyalty open questions — until then, each tenant carries its own `external_consortium` row.", "operationId": "get_hospitality_external_consortium", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.external_consortium" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Consortium code", "type": "string" }, "founded_year": { "title": "Year founded", "type": "integer" }, "home_office_address": { "description": "Home office address", "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "title": "External consortium home office address", "type": "object" }, "id": { "title": "Consortium id", "type": "string" }, "kind": { "enum": [ "lhw_leaders_club", "slh_invited", "preferred_i_prefer", "relais_chateaux_5c", "virtuoso", "mandarin_oriental_fans", "other" ], "title": "Consortium kind", "type": "string" }, "name": { "title": "Consortium name", "type": "string" }, "website_url": { "title": "Website URL", "type": "string" } }, "required": [ "id", "code", "name", "kind" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.external_consortium:read" ] } ], "summary": "Read External consortium", "tags": [ "loyalty" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.external_consortium/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA soft-tier consortium (LHW, SLH, Preferred, Relais & Châteaux, Virtuoso) — properties opt in via the `loyalty_program_for_consortium` link. The consortium runs its own central operations and member identity; the loyalty_program at the property level points back here. Tenant-scoped because the consortium is a tenant-wide entity from Aerandil's perspective; cross-tenant canonicalisation (two Aerandil tenants both running LHW Leaders Club from the same consortium identity) defers per design-spec §G loyalty open questions — until then, each tenant carries its own `external_consortium` row.", "operationId": "get_hospitality_external_consortium_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.external_consortium" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.external_consortium:read" ] } ], "summary": "Read External consortium as of a watermark", "tags": [ "loyalty" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.external_consortium/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA soft-tier consortium (LHW, SLH, Preferred, Relais & Châteaux, Virtuoso) — properties opt in via the `loyalty_program_for_consortium` link. The consortium runs its own central operations and member identity; the loyalty_program at the property level points back here. Tenant-scoped because the consortium is a tenant-wide entity from Aerandil's perspective; cross-tenant canonicalisation (two Aerandil tenants both running LHW Leaders Club from the same consortium identity) defers per design-spec §G loyalty open questions — until then, each tenant carries its own `external_consortium` row.", "operationId": "list_links_hospitality_external_consortium", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.external_consortium:read" ] } ], "summary": "List links of External consortium", "tags": [ "loyalty" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.loyalty_program_for_consortium" ] } } ] }, "/v1/object-types/hospitality.external_consortium/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA soft-tier consortium (LHW, SLH, Preferred, Relais & Châteaux, Virtuoso) — properties opt in via the `loyalty_program_for_consortium` link. The consortium runs its own central operations and member identity; the loyalty_program at the property level points back here. Tenant-scoped because the consortium is a tenant-wide entity from Aerandil's perspective; cross-tenant canonicalisation (two Aerandil tenants both running LHW Leaders Club from the same consortium identity) defers per design-spec §G loyalty open questions — until then, each tenant carries its own `external_consortium` row.", "operationId": "traverse_hospitality_external_consortium", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.loyalty_program_for_consortium" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.external_consortium:read" ] } ], "summary": "Traverse from External consortium", "tags": [ "loyalty" ] } }, "/v1/object-types/hospitality.external_consortium/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA soft-tier consortium (LHW, SLH, Preferred, Relais & Châteaux, Virtuoso) — properties opt in via the `loyalty_program_for_consortium` link. The consortium runs its own central operations and member identity; the loyalty_program at the property level points back here. Tenant-scoped because the consortium is a tenant-wide entity from Aerandil's perspective; cross-tenant canonicalisation (two Aerandil tenants both running LHW Leaders Club from the same consortium identity) defers per design-spec §G loyalty open questions — until then, each tenant carries its own `external_consortium` row.", "operationId": "search_hospitality_external_consortium", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "lhw_leaders_club", "slh_invited", "preferred_i_prefer", "relais_chateaux_5c", "virtuoso", "mandarin_oriental_fans", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "home_office_address" }, "type": { "const": "eq" }, "value": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "website_url" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "website_url" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "website_url" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "website_url" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "founded_year" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "founded_year" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "founded_year" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "code", "name", "kind", "website_url", "founded_year" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.external_consortium" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Consortium code", "type": "string" }, "founded_year": { "title": "Year founded", "type": "integer" }, "home_office_address": { "description": "Home office address", "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "title": "External consortium home office address", "type": "object" }, "id": { "title": "Consortium id", "type": "string" }, "kind": { "enum": [ "lhw_leaders_club", "slh_invited", "preferred_i_prefer", "relais_chateaux_5c", "virtuoso", "mandarin_oriental_fans", "other" ], "title": "Consortium kind", "type": "string" }, "name": { "title": "Consortium name", "type": "string" }, "website_url": { "title": "Website URL", "type": "string" } }, "required": [ "id", "code", "name", "kind" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.external_consortium:read" ] } ], "summary": "Search External consortium", "tags": [ "loyalty" ] } }, "/v1/object-types/hospitality.external_record_reference/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOpaque pointer to a record held in an external source-of-truth system (clinical, legal, financial-audit, regulatory). Aerandil holds the reference, never the record itself; the structural contract is enforced by the absence of a payload field.", "operationId": "get_hospitality_external_record_reference", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.external_record_reference" }, "properties": { "additionalProperties": false, "properties": { "domain": { "enum": [ "clinical", "legal", "financial_audit", "regulatory", "messaging", "identity", "quality_audit" ], "title": "External system domain", "type": "string" }, "id": { "title": "Reference id", "type": "string" }, "opaque_id": { "title": "Opaque external id", "type": "string" }, "record_kind": { "title": "Record kind in the external system", "type": "string" }, "source_updated_at": { "format": "date-time", "title": "Source system last-updated clock", "type": "string" } }, "required": [ "id" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.external_record_reference:read" ] } ], "summary": "Read External record reference", "tags": [ "external_records" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.external_record_reference/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOpaque pointer to a record held in an external source-of-truth system (clinical, legal, financial-audit, regulatory). Aerandil holds the reference, never the record itself; the structural contract is enforced by the absence of a payload field.", "operationId": "get_hospitality_external_record_reference_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.external_record_reference" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.external_record_reference:read" ] } ], "summary": "Read External record reference as of a watermark", "tags": [ "external_records" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.external_record_reference/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOpaque pointer to a record held in an external source-of-truth system (clinical, legal, financial-audit, regulatory). Aerandil holds the reference, never the record itself; the structural contract is enforced by the absence of a payload field.", "operationId": "list_links_hospitality_external_record_reference", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.external_record_reference:read" ] } ], "summary": "List links of External record reference", "tags": [ "external_records" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.allergy_alert_references_external_record", "hospitality.link.appointment_references_external_record", "hospitality.link.assessment_references_external_record", "hospitality.link.external_record_reference_for_provider", "hospitality.link.fraud_assessment_references_external_record", "hospitality.link.guest_id_document_references_external_record", "hospitality.link.guest_message_references_external_record", "hospitality.link.pattern_references_external_record", "hospitality.link.venue_visit_references_external_record" ] } } ] }, "/v1/object-types/hospitality.external_record_reference/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOpaque pointer to a record held in an external source-of-truth system (clinical, legal, financial-audit, regulatory). Aerandil holds the reference, never the record itself; the structural contract is enforced by the absence of a payload field.", "operationId": "traverse_hospitality_external_record_reference", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.allergy_alert_references_external_record", "hospitality.link.appointment_references_external_record", "hospitality.link.assessment_references_external_record", "hospitality.link.external_record_reference_for_provider", "hospitality.link.fraud_assessment_references_external_record", "hospitality.link.guest_id_document_references_external_record", "hospitality.link.guest_message_references_external_record", "hospitality.link.pattern_references_external_record", "hospitality.link.venue_visit_references_external_record" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.external_record_reference:read" ] } ], "summary": "Traverse from External record reference", "tags": [ "external_records" ] } }, "/v1/object-types/hospitality.external_record_reference/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOpaque pointer to a record held in an external source-of-truth system (clinical, legal, financial-audit, regulatory). Aerandil holds the reference, never the record itself; the structural contract is enforced by the absence of a payload field.", "operationId": "search_hospitality_external_record_reference", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "domain" }, "type": { "const": "eq" }, "value": { "enum": [ "clinical", "legal", "financial_audit", "regulatory", "messaging", "identity", "quality_audit" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opaque_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opaque_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opaque_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opaque_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "record_kind" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "record_kind" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "record_kind" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "record_kind" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source_updated_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source_updated_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source_updated_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "domain", "opaque_id", "record_kind", "source_updated_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.external_record_reference" }, "properties": { "additionalProperties": false, "properties": { "domain": { "enum": [ "clinical", "legal", "financial_audit", "regulatory", "messaging", "identity", "quality_audit" ], "title": "External system domain", "type": "string" }, "id": { "title": "Reference id", "type": "string" }, "opaque_id": { "title": "Opaque external id", "type": "string" }, "record_kind": { "title": "Record kind in the external system", "type": "string" }, "source_updated_at": { "format": "date-time", "title": "Source system last-updated clock", "type": "string" } }, "required": [ "id" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.external_record_reference:read" ] } ], "summary": "Search External record reference", "tags": [ "external_records" ] } }, "/v1/object-types/hospitality.fault_type/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA kind of fault a house keeps in its catalogue — \"no hot water\", \"TV remote dead\", \"lift stuck between floors\" (hubOS's failure catalogue). Keyed by `code` within its catalogue: a brand's (`fault_type_at_brand`, shared by the brand's houses) or one house's (`fault_type_at_property`); `define_fault_type` with a code the catalogue holds re-states it in place. It carries the `title` an order raised from it is given, the room `element` it is in, the `category` (the trade that mends it) and the `severity` it starts at — `create_work_order` and `create_public_area_work_order` take `fault_type_id` and fill each one the call does not state. `active`, or `retired` for good (the code stays taken).", "operationId": "get_hospitality_fault_type", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fault_type" }, "properties": { "additionalProperties": false, "properties": { "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "The work-order category an order raised from it starts with — the trade that mends it", "type": "string" }, "code": { "title": "The catalogue's code for it — unique within the catalogue", "type": "string" }, "defined_at": { "format": "date-time", "title": "When it was first put in the catalogue", "type": "string" }, "description": { "title": "Notes for whoever raises or mends it", "type": "string" }, "element": { "enum": [ "light", "air_conditioning", "curtain", "safe", "door", "television", "phone", "wardrobe", "shower", "mirror", "toilet", "pipework", "minibar", "electrical", "other" ], "title": "The room element the fault is in (hubOS's icon), when it is in one", "type": "string" }, "retire_reason": { "title": "Why it was retired", "type": "string" }, "retired_at": { "format": "date-time", "title": "When it was retired", "type": "string" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "title": "The severity an order raised from it starts at", "type": "string" }, "status": { "enum": [ "active", "retired" ], "title": "active, or retired (final)", "type": "string" }, "title": { "title": "The title an order raised from it is given", "type": "string" } }, "required": [ "code", "title", "category", "severity", "status", "defined_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.fault_type:read" ] } ], "summary": "Read Fault type", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.fault_type/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA kind of fault a house keeps in its catalogue — \"no hot water\", \"TV remote dead\", \"lift stuck between floors\" (hubOS's failure catalogue). Keyed by `code` within its catalogue: a brand's (`fault_type_at_brand`, shared by the brand's houses) or one house's (`fault_type_at_property`); `define_fault_type` with a code the catalogue holds re-states it in place. It carries the `title` an order raised from it is given, the room `element` it is in, the `category` (the trade that mends it) and the `severity` it starts at — `create_work_order` and `create_public_area_work_order` take `fault_type_id` and fill each one the call does not state. `active`, or `retired` for good (the code stays taken).", "operationId": "get_hospitality_fault_type_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.fault_type" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.fault_type:read" ] } ], "summary": "Read Fault type as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.fault_type/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA kind of fault a house keeps in its catalogue — \"no hot water\", \"TV remote dead\", \"lift stuck between floors\" (hubOS's failure catalogue). Keyed by `code` within its catalogue: a brand's (`fault_type_at_brand`, shared by the brand's houses) or one house's (`fault_type_at_property`); `define_fault_type` with a code the catalogue holds re-states it in place. It carries the `title` an order raised from it is given, the room `element` it is in, the `category` (the trade that mends it) and the `severity` it starts at — `create_work_order` and `create_public_area_work_order` take `fault_type_id` and fill each one the call does not state. `active`, or `retired` for good (the code stays taken).", "operationId": "list_links_hospitality_fault_type", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.fault_type:read" ] } ], "summary": "List links of Fault type", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.fault_type_at_brand", "hospitality.link.fault_type_at_property", "hospitality.link.work_order_of_fault_type" ] } } ] }, "/v1/object-types/hospitality.fault_type/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA kind of fault a house keeps in its catalogue — \"no hot water\", \"TV remote dead\", \"lift stuck between floors\" (hubOS's failure catalogue). Keyed by `code` within its catalogue: a brand's (`fault_type_at_brand`, shared by the brand's houses) or one house's (`fault_type_at_property`); `define_fault_type` with a code the catalogue holds re-states it in place. It carries the `title` an order raised from it is given, the room `element` it is in, the `category` (the trade that mends it) and the `severity` it starts at — `create_work_order` and `create_public_area_work_order` take `fault_type_id` and fill each one the call does not state. `active`, or `retired` for good (the code stays taken).", "operationId": "traverse_hospitality_fault_type", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.fault_type_at_brand", "hospitality.link.fault_type_at_property", "hospitality.link.work_order_of_fault_type" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.fault_type:read" ] } ], "summary": "Traverse from Fault type", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.fault_type/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA kind of fault a house keeps in its catalogue — \"no hot water\", \"TV remote dead\", \"lift stuck between floors\" (hubOS's failure catalogue). Keyed by `code` within its catalogue: a brand's (`fault_type_at_brand`, shared by the brand's houses) or one house's (`fault_type_at_property`); `define_fault_type` with a code the catalogue holds re-states it in place. It carries the `title` an order raised from it is given, the room `element` it is in, the `category` (the trade that mends it) and the `severity` it starts at — `create_work_order` and `create_public_area_work_order` take `fault_type_id` and fill each one the call does not state. `active`, or `retired` for good (the code stays taken).", "operationId": "search_hospitality_fault_type", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "title" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "title" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "title" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "title" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "element" }, "type": { "const": "eq" }, "value": { "enum": [ "light", "air_conditioning", "curtain", "safe", "door", "television", "phone", "wardrobe", "shower", "mirror", "toilet", "pipework", "minibar", "electrical", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "category" }, "type": { "const": "eq" }, "value": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "severity" }, "type": { "const": "eq" }, "value": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "retired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "defined_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "defined_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "defined_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retire_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retire_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "title", "element", "category", "severity", "description", "status", "defined_at", "retired_at", "retire_reason" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fault_type" }, "properties": { "additionalProperties": false, "properties": { "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "The work-order category an order raised from it starts with — the trade that mends it", "type": "string" }, "code": { "title": "The catalogue's code for it — unique within the catalogue", "type": "string" }, "defined_at": { "format": "date-time", "title": "When it was first put in the catalogue", "type": "string" }, "description": { "title": "Notes for whoever raises or mends it", "type": "string" }, "element": { "enum": [ "light", "air_conditioning", "curtain", "safe", "door", "television", "phone", "wardrobe", "shower", "mirror", "toilet", "pipework", "minibar", "electrical", "other" ], "title": "The room element the fault is in (hubOS's icon), when it is in one", "type": "string" }, "retire_reason": { "title": "Why it was retired", "type": "string" }, "retired_at": { "format": "date-time", "title": "When it was retired", "type": "string" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "title": "The severity an order raised from it starts at", "type": "string" }, "status": { "enum": [ "active", "retired" ], "title": "active, or retired (final)", "type": "string" }, "title": { "title": "The title an order raised from it is given", "type": "string" } }, "required": [ "code", "title", "category", "severity", "status", "defined_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.fault_type:read" ] } ], "summary": "Search Fault type", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.federated_analysis_definition/objects/{id}": { "get": { "description": "Read an existing instance.\n\nVersioned, reviewed computation plan. Names input object types, input field allowlist, forbidden field classes, local feature contract, local code reference / digest, local execution requirements, algorithm family, aggregation method, contribution bounds, privacy mechanisms, epsilon / delta per run, cohort policy, output schema, and required model-card / datasheet / threat-model / DPIA references. Immutable once approved (proposal 0021 §4.2 / §7).", "operationId": "get_hospitality_federated_analysis_definition", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_analysis_definition" }, "properties": { "additionalProperties": false, "properties": { "aggregation_method": { "enum": [ "plain_aggregate_reviewed", "secure_sum", "noisy_count", "noisy_sum", "noisy_mean", "noisy_histogram", "noisy_quantile", "trimmed_mean", "weighted_average", "fedavg", "external_clean_room", "reviewed_custom" ], "title": "Aggregation method", "type": "string" }, "algorithm_family": { "enum": [ "secure_sum", "count_rate", "histogram", "quantile", "calibration_curve", "outcome_decay", "fedavg", "fedxgb", "reviewed_custom" ], "title": "Algorithm family", "type": "string" }, "analysis_kind": { "enum": [ "federated_analytics", "federated_learning", "private_set_intersection", "clean_room_query", "benchmark_export" ], "title": "Analytics / learning / PSI / clean-room / benchmark-export", "type": "string" }, "approved_at": { "format": "date-time", "title": "Set by approval action", "type": "string" }, "approved_by_principal": { "title": "Set by approval action", "type": "string" }, "ci_width_warn_threshold": { "format": "decimal", "title": "Maximum acceptable confidence-interval width (upper − lower) for this definition's outputs; wider intervals warn `output-confidence-interval-too-wide`. Per-definition because CI widths are unitless across queries.", "type": "string" }, "cohort_policy": { "title": "Minimums and suppression rules; may inherit from program (JSON)" }, "composition_group": { "title": "Groups related definitions for privacy-budget composition", "type": "string" }, "contribution_bounds": { "title": "Min / max values, clipping norms, per-participant caps (JSON; required for every approved definition)" }, "datasheet_template_ref": { "title": "Required for benchmark exports and model artifacts", "type": "string" }, "definition_api_name": { "title": "Stable slug within program", "type": "string" }, "delta_per_run": { "format": "decimal", "title": "Required for approximate DP mechanisms", "type": "string" }, "dpia_reference": { "title": "Required when program or definition is high-risk", "type": "string" }, "epsilon_per_run": { "format": "decimal", "title": "Required if DP applies", "type": "string" }, "forbidden_field_classes": { "items": { "type": "string" }, "title": "Defaults include direct_identifier, free_text, payment_secret, etc.", "type": "array" }, "id": { "title": "Definition id", "type": "string" }, "input_field_allowlist": { "items": { "type": "string" }, "title": "Fully qualified field paths or named derived features", "type": "array" }, "input_object_types": { "items": { "type": "string" }, "title": "Aerandil object types eligible for local reads", "type": "array" }, "local_code_digest": { "title": "Required when local_code_reference is set; immutable once approved", "type": "string" }, "local_code_reference": { "title": "Optional code package / container / runner ref", "type": "string" }, "local_execution_requirements": { "title": "Runner version, memory / timeout bounds, offline mode, network egress policy (JSON; validator-enforced shape)" }, "local_feature_contract": { "title": "Bounded schema for local features and aggregate vectors (JSON; typed per-field shape enforced by validators in commit 5)" }, "metric_warn_thresholds": { "title": "Per-metric minimum acceptable validation values (JSON map metric name → number); outputs whose metric_values fall below warn `output-degraded-metrics`." }, "minimum_local_runner_version": { "title": "Effective hard floor (max of program + definition pins, frozen at definition publish time)", "type": "string" }, "model_card_template_ref": { "title": "Required for model artifacts", "type": "string" }, "objective": { "title": "What question the run answers", "type": "string" }, "output_review_required": { "title": "True by default for cross-tenant and model outputs", "type": "boolean" }, "output_schema": { "title": "Bounded output shape; no dynamic arbitrary tables in v1 (JSON)" }, "privacy_mechanisms": { "items": { "enum": [ "cohort_threshold", "contribution_bounding", "differential_privacy", "secure_aggregation", "secure_multiparty_computation", "homomorphic_encryption", "private_set_intersection", "trusted_execution_environment", "manual_statistical_disclosure_control", "none_internal_portfolio_only" ], "type": "string" }, "title": "Privacy mechanisms applied — at least cohort_threshold for every cross-tenant output", "type": "array" }, "program_api_name": { "title": "Stable reference to the program", "type": "string" }, "recommended_local_runner_version": { "title": "Effective soft baseline (max of program + definition pins, frozen at definition publish time)", "type": "string" }, "review_notes": { "title": "Bounded rationale for approval", "type": "string" }, "status": { "enum": [ "draft", "reviewing", "approved", "deprecated", "revoked" ], "title": "Lifecycle status", "type": "string" }, "threat_model_ref": { "title": "Required for cross-tenant programs", "type": "string" }, "version": { "title": "Semver-like; immutable once approved", "type": "string" }, "weighting_method": { "enum": [ "unweighted", "room_nights", "available_rooms", "eligible_events", "revenue", "reviewed_custom" ], "title": "How contributions are weighted in aggregation", "type": "string" } }, "required": [ "id", "program_api_name", "definition_api_name", "version", "status", "analysis_kind", "objective", "input_object_types", "input_field_allowlist", "forbidden_field_classes", "local_feature_contract", "local_execution_requirements", "algorithm_family", "aggregation_method", "weighting_method", "contribution_bounds", "privacy_mechanisms", "cohort_policy", "output_schema", "output_review_required" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_analysis_definition:read" ] } ], "summary": "Read Federated analysis definition", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.federated_analysis_definition/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nVersioned, reviewed computation plan. Names input object types, input field allowlist, forbidden field classes, local feature contract, local code reference / digest, local execution requirements, algorithm family, aggregation method, contribution bounds, privacy mechanisms, epsilon / delta per run, cohort policy, output schema, and required model-card / datasheet / threat-model / DPIA references. Immutable once approved (proposal 0021 §4.2 / §7).", "operationId": "get_hospitality_federated_analysis_definition_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.federated_analysis_definition" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_analysis_definition:read" ] } ], "summary": "Read Federated analysis definition as of a watermark", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.federated_analysis_definition/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nVersioned, reviewed computation plan. Names input object types, input field allowlist, forbidden field classes, local feature contract, local code reference / digest, local execution requirements, algorithm family, aggregation method, contribution bounds, privacy mechanisms, epsilon / delta per run, cohort policy, output schema, and required model-card / datasheet / threat-model / DPIA references. Immutable once approved (proposal 0021 §4.2 / §7).", "operationId": "list_links_hospitality_federated_analysis_definition", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_analysis_definition:read" ] } ], "summary": "List links of Federated analysis definition", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.approval_gate_for_federated_analysis_definition", "hospitality.link.federated_definition_reviewed_by_gate", "hospitality.link.federated_program_has_definition", "hospitality.link.federated_run_uses_definition" ] } } ] }, "/v1/object-types/hospitality.federated_analysis_definition/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nVersioned, reviewed computation plan. Names input object types, input field allowlist, forbidden field classes, local feature contract, local code reference / digest, local execution requirements, algorithm family, aggregation method, contribution bounds, privacy mechanisms, epsilon / delta per run, cohort policy, output schema, and required model-card / datasheet / threat-model / DPIA references. Immutable once approved (proposal 0021 §4.2 / §7).", "operationId": "traverse_hospitality_federated_analysis_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.approval_gate_for_federated_analysis_definition", "hospitality.link.federated_definition_reviewed_by_gate", "hospitality.link.federated_program_has_definition", "hospitality.link.federated_run_uses_definition" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_analysis_definition:read" ] } ], "summary": "Traverse from Federated analysis definition", "tags": [ "federated_intelligence" ] } }, "/v1/object-types/hospitality.federated_analysis_definition/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nVersioned, reviewed computation plan. Names input object types, input field allowlist, forbidden field classes, local feature contract, local code reference / digest, local execution requirements, algorithm family, aggregation method, contribution bounds, privacy mechanisms, epsilon / delta per run, cohort policy, output schema, and required model-card / datasheet / threat-model / DPIA references. Immutable once approved (proposal 0021 §4.2 / §7).", "operationId": "search_hospitality_federated_analysis_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "program_api_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "program_api_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "program_api_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "program_api_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_api_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_api_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_api_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_api_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "version" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "version" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "version" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "version" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "draft", "reviewing", "approved", "deprecated", "revoked" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "analysis_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "federated_analytics", "federated_learning", "private_set_intersection", "clean_room_query", "benchmark_export" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "objective" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "objective" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "input_object_types" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "input_field_allowlist" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "forbidden_field_classes" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "local_feature_contract" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "local_code_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "local_code_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "local_code_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "local_code_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "local_code_digest" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "local_code_digest" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "local_code_digest" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "local_code_digest" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "local_execution_requirements" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "algorithm_family" }, "type": { "const": "eq" }, "value": { "enum": [ "secure_sum", "count_rate", "histogram", "quantile", "calibration_curve", "outcome_decay", "fedavg", "fedxgb", "reviewed_custom" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "aggregation_method" }, "type": { "const": "eq" }, "value": { "enum": [ "plain_aggregate_reviewed", "secure_sum", "noisy_count", "noisy_sum", "noisy_mean", "noisy_histogram", "noisy_quantile", "trimmed_mean", "weighted_average", "fedavg", "external_clean_room", "reviewed_custom" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "weighting_method" }, "type": { "const": "eq" }, "value": { "enum": [ "unweighted", "room_nights", "available_rooms", "eligible_events", "revenue", "reviewed_custom" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contribution_bounds" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "privacy_mechanisms" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "cohort_threshold", "contribution_bounding", "differential_privacy", "secure_aggregation", "secure_multiparty_computation", "homomorphic_encryption", "private_set_intersection", "trusted_execution_environment", "manual_statistical_disclosure_control", "none_internal_portfolio_only" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "epsilon_per_run" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "epsilon_per_run" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "epsilon_per_run" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delta_per_run" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delta_per_run" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delta_per_run" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "composition_group" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "composition_group" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "composition_group" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "composition_group" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "metric_warn_thresholds" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ci_width_warn_threshold" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ci_width_warn_threshold" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ci_width_warn_threshold" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cohort_policy" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "output_schema" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "output_review_required" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_card_template_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_card_template_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_card_template_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_card_template_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "datasheet_template_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "datasheet_template_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "datasheet_template_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "datasheet_template_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "threat_model_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "threat_model_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "threat_model_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "threat_model_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dpia_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dpia_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dpia_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dpia_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "review_notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "review_notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approved_by_principal" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approved_by_principal" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approved_by_principal" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approved_by_principal" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approved_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approved_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approved_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "minimum_local_runner_version" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "minimum_local_runner_version" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "minimum_local_runner_version" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "minimum_local_runner_version" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_local_runner_version" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_local_runner_version" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_local_runner_version" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_local_runner_version" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "program_api_name", "definition_api_name", "version", "status", "analysis_kind", "objective", "local_code_reference", "local_code_digest", "algorithm_family", "aggregation_method", "weighting_method", "epsilon_per_run", "delta_per_run", "composition_group", "ci_width_warn_threshold", "model_card_template_ref", "datasheet_template_ref", "threat_model_ref", "dpia_reference", "review_notes", "approved_by_principal", "approved_at", "minimum_local_runner_version", "recommended_local_runner_version" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_analysis_definition" }, "properties": { "additionalProperties": false, "properties": { "aggregation_method": { "enum": [ "plain_aggregate_reviewed", "secure_sum", "noisy_count", "noisy_sum", "noisy_mean", "noisy_histogram", "noisy_quantile", "trimmed_mean", "weighted_average", "fedavg", "external_clean_room", "reviewed_custom" ], "title": "Aggregation method", "type": "string" }, "algorithm_family": { "enum": [ "secure_sum", "count_rate", "histogram", "quantile", "calibration_curve", "outcome_decay", "fedavg", "fedxgb", "reviewed_custom" ], "title": "Algorithm family", "type": "string" }, "analysis_kind": { "enum": [ "federated_analytics", "federated_learning", "private_set_intersection", "clean_room_query", "benchmark_export" ], "title": "Analytics / learning / PSI / clean-room / benchmark-export", "type": "string" }, "approved_at": { "format": "date-time", "title": "Set by approval action", "type": "string" }, "approved_by_principal": { "title": "Set by approval action", "type": "string" }, "ci_width_warn_threshold": { "format": "decimal", "title": "Maximum acceptable confidence-interval width (upper − lower) for this definition's outputs; wider intervals warn `output-confidence-interval-too-wide`. Per-definition because CI widths are unitless across queries.", "type": "string" }, "cohort_policy": { "title": "Minimums and suppression rules; may inherit from program (JSON)" }, "composition_group": { "title": "Groups related definitions for privacy-budget composition", "type": "string" }, "contribution_bounds": { "title": "Min / max values, clipping norms, per-participant caps (JSON; required for every approved definition)" }, "datasheet_template_ref": { "title": "Required for benchmark exports and model artifacts", "type": "string" }, "definition_api_name": { "title": "Stable slug within program", "type": "string" }, "delta_per_run": { "format": "decimal", "title": "Required for approximate DP mechanisms", "type": "string" }, "dpia_reference": { "title": "Required when program or definition is high-risk", "type": "string" }, "epsilon_per_run": { "format": "decimal", "title": "Required if DP applies", "type": "string" }, "forbidden_field_classes": { "items": { "type": "string" }, "title": "Defaults include direct_identifier, free_text, payment_secret, etc.", "type": "array" }, "id": { "title": "Definition id", "type": "string" }, "input_field_allowlist": { "items": { "type": "string" }, "title": "Fully qualified field paths or named derived features", "type": "array" }, "input_object_types": { "items": { "type": "string" }, "title": "Aerandil object types eligible for local reads", "type": "array" }, "local_code_digest": { "title": "Required when local_code_reference is set; immutable once approved", "type": "string" }, "local_code_reference": { "title": "Optional code package / container / runner ref", "type": "string" }, "local_execution_requirements": { "title": "Runner version, memory / timeout bounds, offline mode, network egress policy (JSON; validator-enforced shape)" }, "local_feature_contract": { "title": "Bounded schema for local features and aggregate vectors (JSON; typed per-field shape enforced by validators in commit 5)" }, "metric_warn_thresholds": { "title": "Per-metric minimum acceptable validation values (JSON map metric name → number); outputs whose metric_values fall below warn `output-degraded-metrics`." }, "minimum_local_runner_version": { "title": "Effective hard floor (max of program + definition pins, frozen at definition publish time)", "type": "string" }, "model_card_template_ref": { "title": "Required for model artifacts", "type": "string" }, "objective": { "title": "What question the run answers", "type": "string" }, "output_review_required": { "title": "True by default for cross-tenant and model outputs", "type": "boolean" }, "output_schema": { "title": "Bounded output shape; no dynamic arbitrary tables in v1 (JSON)" }, "privacy_mechanisms": { "items": { "enum": [ "cohort_threshold", "contribution_bounding", "differential_privacy", "secure_aggregation", "secure_multiparty_computation", "homomorphic_encryption", "private_set_intersection", "trusted_execution_environment", "manual_statistical_disclosure_control", "none_internal_portfolio_only" ], "type": "string" }, "title": "Privacy mechanisms applied — at least cohort_threshold for every cross-tenant output", "type": "array" }, "program_api_name": { "title": "Stable reference to the program", "type": "string" }, "recommended_local_runner_version": { "title": "Effective soft baseline (max of program + definition pins, frozen at definition publish time)", "type": "string" }, "review_notes": { "title": "Bounded rationale for approval", "type": "string" }, "status": { "enum": [ "draft", "reviewing", "approved", "deprecated", "revoked" ], "title": "Lifecycle status", "type": "string" }, "threat_model_ref": { "title": "Required for cross-tenant programs", "type": "string" }, "version": { "title": "Semver-like; immutable once approved", "type": "string" }, "weighting_method": { "enum": [ "unweighted", "room_nights", "available_rooms", "eligible_events", "revenue", "reviewed_custom" ], "title": "How contributions are weighted in aggregation", "type": "string" } }, "required": [ "id", "program_api_name", "definition_api_name", "version", "status", "analysis_kind", "objective", "input_object_types", "input_field_allowlist", "forbidden_field_classes", "local_feature_contract", "local_execution_requirements", "algorithm_family", "aggregation_method", "weighting_method", "contribution_bounds", "privacy_mechanisms", "cohort_policy", "output_schema", "output_review_required" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_analysis_definition:read" ] } ], "summary": "Search Federated analysis definition", "tags": [ "federated_intelligence" ] } }, "/v1/object-types/hospitality.federated_cohort_definition/objects/{id}": { "get": { "description": "Read an existing instance.\n\nReusable cohort / comp-set policy. Selection rules, geography granularity, time-window rule, minimum thresholds, max- contributor share, stratification fields, suppression rules, and optional excluded-tenants list. A cohort defines who can be compared, not what is computed (proposal 0021 §4.3).", "operationId": "get_hospitality_federated_cohort_definition", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_cohort_definition" }, "properties": { "additionalProperties": false, "properties": { "approved_at": { "format": "date-time", "title": "Set by review", "type": "string" }, "cohort_api_name": { "title": "Stable slug", "type": "string" }, "cohort_kind": { "enum": [ "market_segment", "property_type", "portfolio_segment", "service_model", "risk_tier", "revenue_band", "usali_department", "agent_use_case", "custom_reviewed" ], "title": "Cohort kind", "type": "string" }, "display_name": { "title": "Human-readable name", "type": "string" }, "dropout_tolerance_fraction": { "format": "decimal", "title": "0022 §11.4 honest-majority threshold for secure-aggregation runs: the fraction of dispatched participants that may drop out (terminal dispatch failure / envelope expiry) before the run is failed and its privacy-budget reservation released. Decimal in (0,1]; absent means the §11.4 default of 0.5.", "type": "string" }, "excluded_tenants": { "items": { "type": "string" }, "title": "Rare; conflict / legal exclusions. Not visible to participants unless allowed.", "type": "array" }, "geography_granularity": { "enum": [ "none", "country", "region", "city", "market", "custom_reviewed" ], "title": "Geography granularity", "type": "string" }, "id": { "title": "Cohort id", "type": "string" }, "max_contributor_share": { "format": "decimal", "title": "Prevents one participant from dominating output (decimal in [0,1])", "type": "string" }, "minimum_properties": { "title": "Overrides program default if stricter", "type": "integer" }, "minimum_subjects": { "title": "Required for person-affecting outputs", "type": "integer" }, "minimum_tenants": { "title": "Overrides program default if stricter", "type": "integer" }, "program_api_name": { "title": "Owning program reference", "type": "string" }, "selection_rules": { "title": "Typed rules over property / venue / outlet / market metadata (JSON)" }, "status": { "enum": [ "draft", "approved", "deprecated" ], "title": "Lifecycle status", "type": "string" }, "stratification_fields": { "items": { "type": "string" }, "title": "Allowed output slices, e.g. market class or property type", "type": "array" }, "suppression_rules": { "title": "What to suppress when thresholds fail (JSON)" }, "time_window_rule": { "title": "Rolling or fixed reporting window (JSON)" } }, "required": [ "id", "cohort_api_name", "program_api_name", "display_name", "cohort_kind", "selection_rules", "geography_granularity", "time_window_rule", "minimum_tenants", "minimum_properties", "max_contributor_share", "stratification_fields", "suppression_rules", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_cohort_definition:read" ] } ], "summary": "Read Federated cohort definition", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.federated_cohort_definition/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nReusable cohort / comp-set policy. Selection rules, geography granularity, time-window rule, minimum thresholds, max- contributor share, stratification fields, suppression rules, and optional excluded-tenants list. A cohort defines who can be compared, not what is computed (proposal 0021 §4.3).", "operationId": "get_hospitality_federated_cohort_definition_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.federated_cohort_definition" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_cohort_definition:read" ] } ], "summary": "Read Federated cohort definition as of a watermark", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.federated_cohort_definition/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nReusable cohort / comp-set policy. Selection rules, geography granularity, time-window rule, minimum thresholds, max- contributor share, stratification fields, suppression rules, and optional excluded-tenants list. A cohort defines who can be compared, not what is computed (proposal 0021 §4.3).", "operationId": "list_links_hospitality_federated_cohort_definition", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_cohort_definition:read" ] } ], "summary": "List links of Federated cohort definition", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.federated_program_has_cohort", "hospitality.link.federated_run_uses_cohort" ] } } ] }, "/v1/object-types/hospitality.federated_cohort_definition/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nReusable cohort / comp-set policy. Selection rules, geography granularity, time-window rule, minimum thresholds, max- contributor share, stratification fields, suppression rules, and optional excluded-tenants list. A cohort defines who can be compared, not what is computed (proposal 0021 §4.3).", "operationId": "traverse_hospitality_federated_cohort_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.federated_program_has_cohort", "hospitality.link.federated_run_uses_cohort" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_cohort_definition:read" ] } ], "summary": "Traverse from Federated cohort definition", "tags": [ "federated_intelligence" ] } }, "/v1/object-types/hospitality.federated_cohort_definition/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nReusable cohort / comp-set policy. Selection rules, geography granularity, time-window rule, minimum thresholds, max- contributor share, stratification fields, suppression rules, and optional excluded-tenants list. A cohort defines who can be compared, not what is computed (proposal 0021 §4.3).", "operationId": "search_hospitality_federated_cohort_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cohort_api_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cohort_api_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cohort_api_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cohort_api_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "program_api_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "program_api_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "program_api_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "program_api_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cohort_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "market_segment", "property_type", "portfolio_segment", "service_model", "risk_tier", "revenue_band", "usali_department", "agent_use_case", "custom_reviewed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "selection_rules" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "geography_granularity" }, "type": { "const": "eq" }, "value": { "enum": [ "none", "country", "region", "city", "market", "custom_reviewed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "time_window_rule" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "minimum_tenants" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "minimum_tenants" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "minimum_tenants" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "minimum_properties" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "minimum_properties" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "minimum_properties" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "minimum_subjects" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "minimum_subjects" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "minimum_subjects" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_contributor_share" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_contributor_share" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_contributor_share" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dropout_tolerance_fraction" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dropout_tolerance_fraction" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dropout_tolerance_fraction" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "stratification_fields" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "suppression_rules" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "excluded_tenants" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "draft", "approved", "deprecated" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approved_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approved_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approved_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "cohort_api_name", "program_api_name", "display_name", "cohort_kind", "geography_granularity", "minimum_tenants", "minimum_properties", "minimum_subjects", "max_contributor_share", "dropout_tolerance_fraction", "status", "approved_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_cohort_definition" }, "properties": { "additionalProperties": false, "properties": { "approved_at": { "format": "date-time", "title": "Set by review", "type": "string" }, "cohort_api_name": { "title": "Stable slug", "type": "string" }, "cohort_kind": { "enum": [ "market_segment", "property_type", "portfolio_segment", "service_model", "risk_tier", "revenue_band", "usali_department", "agent_use_case", "custom_reviewed" ], "title": "Cohort kind", "type": "string" }, "display_name": { "title": "Human-readable name", "type": "string" }, "dropout_tolerance_fraction": { "format": "decimal", "title": "0022 §11.4 honest-majority threshold for secure-aggregation runs: the fraction of dispatched participants that may drop out (terminal dispatch failure / envelope expiry) before the run is failed and its privacy-budget reservation released. Decimal in (0,1]; absent means the §11.4 default of 0.5.", "type": "string" }, "excluded_tenants": { "items": { "type": "string" }, "title": "Rare; conflict / legal exclusions. Not visible to participants unless allowed.", "type": "array" }, "geography_granularity": { "enum": [ "none", "country", "region", "city", "market", "custom_reviewed" ], "title": "Geography granularity", "type": "string" }, "id": { "title": "Cohort id", "type": "string" }, "max_contributor_share": { "format": "decimal", "title": "Prevents one participant from dominating output (decimal in [0,1])", "type": "string" }, "minimum_properties": { "title": "Overrides program default if stricter", "type": "integer" }, "minimum_subjects": { "title": "Required for person-affecting outputs", "type": "integer" }, "minimum_tenants": { "title": "Overrides program default if stricter", "type": "integer" }, "program_api_name": { "title": "Owning program reference", "type": "string" }, "selection_rules": { "title": "Typed rules over property / venue / outlet / market metadata (JSON)" }, "status": { "enum": [ "draft", "approved", "deprecated" ], "title": "Lifecycle status", "type": "string" }, "stratification_fields": { "items": { "type": "string" }, "title": "Allowed output slices, e.g. market class or property type", "type": "array" }, "suppression_rules": { "title": "What to suppress when thresholds fail (JSON)" }, "time_window_rule": { "title": "Rolling or fixed reporting window (JSON)" } }, "required": [ "id", "cohort_api_name", "program_api_name", "display_name", "cohort_kind", "selection_rules", "geography_granularity", "time_window_rule", "minimum_tenants", "minimum_properties", "max_contributor_share", "stratification_fields", "suppression_rules", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_cohort_definition:read" ] } ], "summary": "Search Federated cohort definition", "tags": [ "federated_intelligence" ] } }, "/v1/object-types/hospitality.federated_contribution/objects/{id}": { "get": { "description": "Read an existing instance.\n\nMetadata for one participant's local contribution to a run. Stores hashes, bucketed counts, payload reference / hash, validation warnings, optional attestation reference. **Does not store raw local records, raw guest text, direct identifiers, PAN, PHI, or clinical detail** — those are rejected structurally by the contribution validators (proposal 0021 §4.7 / §7).", "operationId": "get_hospitality_federated_contribution", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_contribution" }, "properties": { "additionalProperties": false, "properties": { "accepted_at": { "format": "date-time", "title": "Set by validation", "type": "string" }, "attestation_reference": { "title": "TEE / runner attestation if used", "type": "string" }, "clipping_applied": { "title": "Required true for model updates (validator enforced)", "type": "boolean" }, "contribution_fingerprint": { "title": "SHA-256 over the contribution ledger payload. Same ledger key with a different fingerprint is rejected.", "type": "string" }, "contribution_kind": { "enum": [ "encrypted_aggregate", "noisy_aggregate", "model_update", "metrics_only", "attestation_only" ], "title": "Encrypted aggregate / noisy aggregate / model update / metrics only / attestation only", "type": "string" }, "contribution_slot": { "title": "Slot discriminator when a definition declares multiple slots; null for the default single-slot path", "type": "string" }, "delta_spent": { "format": "decimal", "title": "Local DP spend", "type": "string" }, "epsilon_spent": { "format": "decimal", "title": "Local DP spend", "type": "string" }, "id": { "title": "Contribution id", "type": "string" }, "input_snapshot_hash": { "title": "Hash over local eligible input snapshot metadata; never raw data", "type": "string" }, "input_window_end": { "format": "date-time", "title": "Must match run", "type": "string" }, "input_window_start": { "format": "date-time", "title": "Must match run", "type": "string" }, "local_code_digest": { "title": "Must match approved definition unless reviewed override", "type": "string" }, "local_record_count_bucket": { "enum": [ "lt_10", "10_49", "50_99", "100_499", "500_999", "1000_plus" ], "title": "Bucketed record count; exact counts stay local unless reviewed", "type": "string" }, "local_runner_version": { "title": "Runner or agent version", "type": "string" }, "local_subject_count_bucket": { "enum": [ "lt_10", "10_49", "50_99", "100_499", "500_999", "1000_plus" ], "title": "Required for person-affecting definitions", "type": "string" }, "minimum_local_runner_version_at_submission": { "title": "Snapshot of the effective hard floor from the contribution's definition at action time", "type": "string" }, "participation_id": { "title": "Participation id", "type": "string" }, "payload_hash": { "title": "Required when payload_reference is set", "type": "string" }, "payload_reference": { "title": "Encrypted payload / clean-room output / secure aggregation share reference. Never the payload body itself.", "type": "string" }, "payload_size_bytes": { "title": "Safety bound", "type": "integer" }, "recommended_local_runner_version_at_submission": { "title": "Snapshot of the effective soft baseline from the contribution's definition at action time", "type": "string" }, "rejection_reason": { "title": "Bounded", "type": "string" }, "run_id": { "title": "Federated run id", "type": "string" }, "secure_aggregation_mask_ref": { "title": "Optional protocol metadata", "type": "string" }, "status": { "enum": [ "requested", "local_prepared", "submitted", "accepted", "rejected", "suppressed", "withdrawn", "expired" ], "title": "Lifecycle status", "type": "string" }, "submitted_at": { "format": "date-time", "title": "Set by action", "type": "string" }, "validation_warnings": { "items": { "type": "string" }, "title": "Local runner warnings (bounded text array)", "type": "array" } }, "required": [ "id", "run_id", "participation_id", "status", "contribution_kind", "local_code_digest", "local_runner_version", "input_snapshot_hash", "input_window_start", "input_window_end", "contribution_fingerprint", "local_record_count_bucket", "clipping_applied", "validation_warnings" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_contribution:read" ] } ], "summary": "Read Federated contribution", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.federated_contribution/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nMetadata for one participant's local contribution to a run. Stores hashes, bucketed counts, payload reference / hash, validation warnings, optional attestation reference. **Does not store raw local records, raw guest text, direct identifiers, PAN, PHI, or clinical detail** — those are rejected structurally by the contribution validators (proposal 0021 §4.7 / §7).", "operationId": "get_hospitality_federated_contribution_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.federated_contribution" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_contribution:read" ] } ], "summary": "Read Federated contribution as of a watermark", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.federated_contribution/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nMetadata for one participant's local contribution to a run. Stores hashes, bucketed counts, payload reference / hash, validation warnings, optional attestation reference. **Does not store raw local records, raw guest text, direct identifiers, PAN, PHI, or clinical detail** — those are rejected structurally by the contribution validators (proposal 0021 §4.7 / §7).", "operationId": "list_links_hospitality_federated_contribution", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_contribution:read" ] } ], "summary": "List links of Federated contribution", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.federated_contribution_for_run", "hospitality.link.federated_contribution_from_participation" ] } } ] }, "/v1/object-types/hospitality.federated_contribution/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nMetadata for one participant's local contribution to a run. Stores hashes, bucketed counts, payload reference / hash, validation warnings, optional attestation reference. **Does not store raw local records, raw guest text, direct identifiers, PAN, PHI, or clinical detail** — those are rejected structurally by the contribution validators (proposal 0021 §4.7 / §7).", "operationId": "traverse_hospitality_federated_contribution", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.federated_contribution_for_run", "hospitality.link.federated_contribution_from_participation" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_contribution:read" ] } ], "summary": "Traverse from Federated contribution", "tags": [ "federated_intelligence" ] } }, "/v1/object-types/hospitality.federated_contribution/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nMetadata for one participant's local contribution to a run. Stores hashes, bucketed counts, payload reference / hash, validation warnings, optional attestation reference. **Does not store raw local records, raw guest text, direct identifiers, PAN, PHI, or clinical detail** — those are rejected structurally by the contribution validators (proposal 0021 §4.7 / §7).", "operationId": "search_hospitality_federated_contribution", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "run_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "run_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "run_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "run_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "participation_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "participation_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "participation_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "participation_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "requested", "local_prepared", "submitted", "accepted", "rejected", "suppressed", "withdrawn", "expired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contribution_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "encrypted_aggregate", "noisy_aggregate", "model_update", "metrics_only", "attestation_only" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contribution_slot" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contribution_slot" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contribution_slot" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contribution_slot" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "local_code_digest" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "local_code_digest" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "local_code_digest" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "local_code_digest" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "local_runner_version" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "local_runner_version" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "local_runner_version" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "local_runner_version" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "input_snapshot_hash" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "input_snapshot_hash" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "input_snapshot_hash" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "input_snapshot_hash" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "input_window_start" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "input_window_start" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "input_window_start" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "input_window_end" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "input_window_end" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "input_window_end" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contribution_fingerprint" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contribution_fingerprint" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contribution_fingerprint" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contribution_fingerprint" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "local_record_count_bucket" }, "type": { "const": "eq" }, "value": { "enum": [ "lt_10", "10_49", "50_99", "100_499", "500_999", "1000_plus" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "local_subject_count_bucket" }, "type": { "const": "eq" }, "value": { "enum": [ "lt_10", "10_49", "50_99", "100_499", "500_999", "1000_plus" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payload_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payload_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payload_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payload_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payload_hash" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payload_hash" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payload_hash" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payload_hash" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payload_size_bytes" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payload_size_bytes" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payload_size_bytes" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "secure_aggregation_mask_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "secure_aggregation_mask_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "secure_aggregation_mask_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "secure_aggregation_mask_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "epsilon_spent" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "epsilon_spent" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "epsilon_spent" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delta_spent" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delta_spent" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delta_spent" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "clipping_applied" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "validation_warnings" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "attestation_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "attestation_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "attestation_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "attestation_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "submitted_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "submitted_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "submitted_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "accepted_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "accepted_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "accepted_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejection_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejection_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "minimum_local_runner_version_at_submission" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "minimum_local_runner_version_at_submission" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "minimum_local_runner_version_at_submission" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "minimum_local_runner_version_at_submission" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_local_runner_version_at_submission" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_local_runner_version_at_submission" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_local_runner_version_at_submission" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_local_runner_version_at_submission" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "run_id", "participation_id", "status", "contribution_kind", "contribution_slot", "local_code_digest", "local_runner_version", "input_snapshot_hash", "input_window_start", "input_window_end", "contribution_fingerprint", "local_record_count_bucket", "local_subject_count_bucket", "payload_reference", "payload_hash", "payload_size_bytes", "secure_aggregation_mask_ref", "epsilon_spent", "delta_spent", "attestation_reference", "submitted_at", "accepted_at", "rejection_reason", "minimum_local_runner_version_at_submission", "recommended_local_runner_version_at_submission" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_contribution" }, "properties": { "additionalProperties": false, "properties": { "accepted_at": { "format": "date-time", "title": "Set by validation", "type": "string" }, "attestation_reference": { "title": "TEE / runner attestation if used", "type": "string" }, "clipping_applied": { "title": "Required true for model updates (validator enforced)", "type": "boolean" }, "contribution_fingerprint": { "title": "SHA-256 over the contribution ledger payload. Same ledger key with a different fingerprint is rejected.", "type": "string" }, "contribution_kind": { "enum": [ "encrypted_aggregate", "noisy_aggregate", "model_update", "metrics_only", "attestation_only" ], "title": "Encrypted aggregate / noisy aggregate / model update / metrics only / attestation only", "type": "string" }, "contribution_slot": { "title": "Slot discriminator when a definition declares multiple slots; null for the default single-slot path", "type": "string" }, "delta_spent": { "format": "decimal", "title": "Local DP spend", "type": "string" }, "epsilon_spent": { "format": "decimal", "title": "Local DP spend", "type": "string" }, "id": { "title": "Contribution id", "type": "string" }, "input_snapshot_hash": { "title": "Hash over local eligible input snapshot metadata; never raw data", "type": "string" }, "input_window_end": { "format": "date-time", "title": "Must match run", "type": "string" }, "input_window_start": { "format": "date-time", "title": "Must match run", "type": "string" }, "local_code_digest": { "title": "Must match approved definition unless reviewed override", "type": "string" }, "local_record_count_bucket": { "enum": [ "lt_10", "10_49", "50_99", "100_499", "500_999", "1000_plus" ], "title": "Bucketed record count; exact counts stay local unless reviewed", "type": "string" }, "local_runner_version": { "title": "Runner or agent version", "type": "string" }, "local_subject_count_bucket": { "enum": [ "lt_10", "10_49", "50_99", "100_499", "500_999", "1000_plus" ], "title": "Required for person-affecting definitions", "type": "string" }, "minimum_local_runner_version_at_submission": { "title": "Snapshot of the effective hard floor from the contribution's definition at action time", "type": "string" }, "participation_id": { "title": "Participation id", "type": "string" }, "payload_hash": { "title": "Required when payload_reference is set", "type": "string" }, "payload_reference": { "title": "Encrypted payload / clean-room output / secure aggregation share reference. Never the payload body itself.", "type": "string" }, "payload_size_bytes": { "title": "Safety bound", "type": "integer" }, "recommended_local_runner_version_at_submission": { "title": "Snapshot of the effective soft baseline from the contribution's definition at action time", "type": "string" }, "rejection_reason": { "title": "Bounded", "type": "string" }, "run_id": { "title": "Federated run id", "type": "string" }, "secure_aggregation_mask_ref": { "title": "Optional protocol metadata", "type": "string" }, "status": { "enum": [ "requested", "local_prepared", "submitted", "accepted", "rejected", "suppressed", "withdrawn", "expired" ], "title": "Lifecycle status", "type": "string" }, "submitted_at": { "format": "date-time", "title": "Set by action", "type": "string" }, "validation_warnings": { "items": { "type": "string" }, "title": "Local runner warnings (bounded text array)", "type": "array" } }, "required": [ "id", "run_id", "participation_id", "status", "contribution_kind", "local_code_digest", "local_runner_version", "input_snapshot_hash", "input_window_start", "input_window_end", "contribution_fingerprint", "local_record_count_bucket", "clipping_applied", "validation_warnings" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_contribution:read" ] } ], "summary": "Search Federated contribution", "tags": [ "federated_intelligence" ] } }, "/v1/object-types/hospitality.federated_intelligence_program/objects/{id}": { "get": { "description": "Read an existing instance.\n\nDurable governance envelope for a family of related cross-tenant analyses or model runs. Carries purpose, governance tier, allowed analysis kinds, default minimum cohort rules, default privacy mechanisms, budget periods, legal-basis / DPA / DPIA references, coordinator metadata, and the `review_gate_policy` driving proposal 0020 approval gates. Cross-tenant programs require DPA references and structural minimum cohort floors (proposal 0021 §4.1 / §7).", "operationId": "get_hospitality_federated_intelligence_program", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_intelligence_program" }, "properties": { "additionalProperties": false, "properties": { "allowed_analysis_kinds": { "items": { "enum": [ "federated_analytics", "federated_learning", "private_set_intersection", "clean_room_query", "benchmark_export" ], "type": "string" }, "title": "Analytics first; learning requires review", "type": "array" }, "allowed_output_kinds": { "items": { "enum": [ "benchmark_report", "calibration_curve", "aggregate_metric", "model_artifact", "signal_package", "governance_card" ], "type": "string" }, "title": "Benchmark reports, calibration curves, model artifacts, signal packages", "type": "array" }, "api_name": { "title": "Stable slug; unique within owner scope", "type": "string" }, "approved_at": { "format": "date-time", "title": "Set only via approval action", "type": "string" }, "coordinator_kind": { "enum": [ "aerandil", "tenant", "consortium", "third_party_clean_room" ], "title": "Coordinator: aerandil / tenant / consortium / third_party_clean_room", "type": "string" }, "coordinator_reference": { "title": "Optional system or contract reference", "type": "string" }, "created_by_principal": { "title": "`Principal::stable_id()` of the proposer", "type": "string" }, "default_delta": { "format": "decimal", "title": "Required when default_epsilon set and mechanism needs delta", "type": "string" }, "default_epsilon": { "format": "decimal", "title": "Program-level default for DP definitions; null when DP not applicable", "type": "string" }, "default_max_contributor_share": { "format": "decimal", "title": "No participant may dominate output beyond this share (decimal in [0,1])", "type": "string" }, "default_min_properties": { "title": "Hard minimum for cross-tenant outputs", "type": "integer" }, "default_min_subjects": { "title": "Required when output can be person-affecting", "type": "integer" }, "default_min_tenants": { "title": "Hard minimum for cross-tenant outputs (>= 3 for cross_tenant_network)", "type": "integer" }, "default_privacy_mechanisms": { "items": { "enum": [ "cohort_threshold", "contribution_bounding", "differential_privacy", "secure_aggregation", "secure_multiparty_computation", "homomorphic_encryption", "private_set_intersection", "trusted_execution_environment", "manual_statistical_disclosure_control", "none_internal_portfolio_only" ], "type": "string" }, "title": "Default privacy mechanisms applied per definition", "type": "array" }, "description": { "title": "Operator-facing summary. No marketing claims.", "type": "string" }, "display_name": { "title": "Human-readable name", "type": "string" }, "downstream_use_policy": { "title": "Allowed uses for outputs; machine-readable policy can follow later", "type": "string" }, "dpa_reference": { "title": "DPA / consortium-agreement reference. Required for cross-tenant programs unless reviewer waives.", "type": "string" }, "dpia_reference": { "title": "Required for high-risk or person-affecting programs", "type": "string" }, "effective_from": { "format": "date-time", "title": "Effective from", "type": "string" }, "effective_to": { "format": "date-time", "title": "Effective to", "type": "string" }, "governance_tier": { "enum": [ "internal_portfolio", "cross_tenant_network", "consortium_governed", "high_risk_review" ], "title": "Governance tier — floor for cohort / privacy validators", "type": "string" }, "id": { "title": "Program id", "type": "string" }, "legal_basis_summary": { "title": "Bounded summary; full legal document via external ref", "type": "string" }, "minimum_local_runner_version": { "title": "Hard floor — contributions whose `local_runner_version` parses below this semver are rejected at action time (AWS Lambda deprecation floor)", "type": "string" }, "owner_ref": { "title": "Consortium or operator governance reference when owner is not a single tenant", "type": "string" }, "owner_scope": { "enum": [ "tenant", "consortium", "aerandil_managed" ], "title": "Owner scope: tenant / consortium / aerandil_managed", "type": "string" }, "participant_benefit_policy": { "title": "What participating tenants receive in return", "type": "string" }, "privacy_budget_period": { "enum": [ "run", "day", "month", "quarter", "year", "lifetime" ], "title": "Default period for budget accounting", "type": "string" }, "purpose": { "enum": [ "rate_recommendation_calibration", "fraud_signal_calibration", "service_recovery_benchmark", "agent_quality_benchmark", "payment_review_benchmark", "outlet_profitability_benchmark", "energy_water_waste_benchmark", "operations_research", "consortium_standardization", "reviewed_custom" ], "title": "Drives legal / review expectations", "type": "string" }, "recommended_local_runner_version": { "title": "Soft baseline — contributions whose `local_runner_version` parses below this semver emit `contribution_runner_version_outdated_warns` (Stripe-style API-version upgrade signal)", "type": "string" }, "review_gate_policy": { "title": "Names which definitions and outputs require proposal 0020 approval gates (JSON; per-tier required-review map)." }, "status": { "enum": [ "draft", "reviewing", "active", "paused", "deprecated", "retired" ], "title": "Lifecycle status", "type": "string" } }, "required": [ "id", "api_name", "display_name", "owner_scope", "purpose", "status", "governance_tier", "allowed_analysis_kinds", "allowed_output_kinds", "default_min_tenants", "default_min_properties", "default_max_contributor_share", "default_privacy_mechanisms", "privacy_budget_period", "coordinator_kind", "review_gate_policy" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_intelligence_program:read" ] } ], "summary": "Read Federated intelligence program", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.federated_intelligence_program/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nDurable governance envelope for a family of related cross-tenant analyses or model runs. Carries purpose, governance tier, allowed analysis kinds, default minimum cohort rules, default privacy mechanisms, budget periods, legal-basis / DPA / DPIA references, coordinator metadata, and the `review_gate_policy` driving proposal 0020 approval gates. Cross-tenant programs require DPA references and structural minimum cohort floors (proposal 0021 §4.1 / §7).", "operationId": "get_hospitality_federated_intelligence_program_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.federated_intelligence_program" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_intelligence_program:read" ] } ], "summary": "Read Federated intelligence program as of a watermark", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.federated_intelligence_program/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nDurable governance envelope for a family of related cross-tenant analyses or model runs. Carries purpose, governance tier, allowed analysis kinds, default minimum cohort rules, default privacy mechanisms, budget periods, legal-basis / DPA / DPIA references, coordinator metadata, and the `review_gate_policy` driving proposal 0020 approval gates. Cross-tenant programs require DPA references and structural minimum cohort floors (proposal 0021 §4.1 / §7).", "operationId": "list_links_hospitality_federated_intelligence_program", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_intelligence_program:read" ] } ], "summary": "List links of Federated intelligence program", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.federated_participation_in_program", "hospitality.link.federated_program_has_cohort", "hospitality.link.federated_program_has_definition" ] } } ] }, "/v1/object-types/hospitality.federated_intelligence_program/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nDurable governance envelope for a family of related cross-tenant analyses or model runs. Carries purpose, governance tier, allowed analysis kinds, default minimum cohort rules, default privacy mechanisms, budget periods, legal-basis / DPA / DPIA references, coordinator metadata, and the `review_gate_policy` driving proposal 0020 approval gates. Cross-tenant programs require DPA references and structural minimum cohort floors (proposal 0021 §4.1 / §7).", "operationId": "traverse_hospitality_federated_intelligence_program", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.federated_participation_in_program", "hospitality.link.federated_program_has_cohort", "hospitality.link.federated_program_has_definition" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_intelligence_program:read" ] } ], "summary": "Traverse from Federated intelligence program", "tags": [ "federated_intelligence" ] } }, "/v1/object-types/hospitality.federated_intelligence_program/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nDurable governance envelope for a family of related cross-tenant analyses or model runs. Carries purpose, governance tier, allowed analysis kinds, default minimum cohort rules, default privacy mechanisms, budget periods, legal-basis / DPA / DPIA references, coordinator metadata, and the `review_gate_policy` driving proposal 0020 approval gates. Cross-tenant programs require DPA references and structural minimum cohort floors (proposal 0021 §4.1 / §7).", "operationId": "search_hospitality_federated_intelligence_program", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "api_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "api_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "api_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "api_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "owner_scope" }, "type": { "const": "eq" }, "value": { "enum": [ "tenant", "consortium", "aerandil_managed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "owner_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "owner_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "owner_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "owner_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "purpose" }, "type": { "const": "eq" }, "value": { "enum": [ "rate_recommendation_calibration", "fraud_signal_calibration", "service_recovery_benchmark", "agent_quality_benchmark", "payment_review_benchmark", "outlet_profitability_benchmark", "energy_water_waste_benchmark", "operations_research", "consortium_standardization", "reviewed_custom" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "draft", "reviewing", "active", "paused", "deprecated", "retired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "governance_tier" }, "type": { "const": "eq" }, "value": { "enum": [ "internal_portfolio", "cross_tenant_network", "consortium_governed", "high_risk_review" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "allowed_analysis_kinds" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "federated_analytics", "federated_learning", "private_set_intersection", "clean_room_query", "benchmark_export" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "allowed_output_kinds" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "benchmark_report", "calibration_curve", "aggregate_metric", "model_artifact", "signal_package", "governance_card" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "default_min_tenants" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "default_min_tenants" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "default_min_tenants" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "default_min_properties" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "default_min_properties" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "default_min_properties" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "default_min_subjects" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "default_min_subjects" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "default_min_subjects" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "default_max_contributor_share" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "default_max_contributor_share" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "default_max_contributor_share" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "default_privacy_mechanisms" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "cohort_threshold", "contribution_bounding", "differential_privacy", "secure_aggregation", "secure_multiparty_computation", "homomorphic_encryption", "private_set_intersection", "trusted_execution_environment", "manual_statistical_disclosure_control", "none_internal_portfolio_only" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "default_epsilon" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "default_epsilon" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "default_epsilon" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "default_delta" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "default_delta" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "default_delta" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "privacy_budget_period" }, "type": { "const": "eq" }, "value": { "enum": [ "run", "day", "month", "quarter", "year", "lifetime" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "legal_basis_summary" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "legal_basis_summary" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dpa_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dpa_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dpa_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dpa_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dpia_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dpia_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dpia_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dpia_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "coordinator_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "aerandil", "tenant", "consortium", "third_party_clean_room" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "coordinator_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "coordinator_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "coordinator_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "coordinator_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "review_gate_policy" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "participant_benefit_policy" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "participant_benefit_policy" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "downstream_use_policy" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "downstream_use_policy" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "created_by_principal" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "created_by_principal" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "created_by_principal" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "created_by_principal" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approved_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approved_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approved_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "minimum_local_runner_version" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "minimum_local_runner_version" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "minimum_local_runner_version" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "minimum_local_runner_version" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_local_runner_version" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_local_runner_version" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_local_runner_version" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_local_runner_version" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "api_name", "display_name", "description", "owner_scope", "owner_ref", "purpose", "status", "governance_tier", "default_min_tenants", "default_min_properties", "default_min_subjects", "default_max_contributor_share", "default_epsilon", "default_delta", "privacy_budget_period", "legal_basis_summary", "dpa_reference", "dpia_reference", "coordinator_kind", "coordinator_reference", "participant_benefit_policy", "downstream_use_policy", "effective_from", "effective_to", "created_by_principal", "approved_at", "minimum_local_runner_version", "recommended_local_runner_version" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_intelligence_program" }, "properties": { "additionalProperties": false, "properties": { "allowed_analysis_kinds": { "items": { "enum": [ "federated_analytics", "federated_learning", "private_set_intersection", "clean_room_query", "benchmark_export" ], "type": "string" }, "title": "Analytics first; learning requires review", "type": "array" }, "allowed_output_kinds": { "items": { "enum": [ "benchmark_report", "calibration_curve", "aggregate_metric", "model_artifact", "signal_package", "governance_card" ], "type": "string" }, "title": "Benchmark reports, calibration curves, model artifacts, signal packages", "type": "array" }, "api_name": { "title": "Stable slug; unique within owner scope", "type": "string" }, "approved_at": { "format": "date-time", "title": "Set only via approval action", "type": "string" }, "coordinator_kind": { "enum": [ "aerandil", "tenant", "consortium", "third_party_clean_room" ], "title": "Coordinator: aerandil / tenant / consortium / third_party_clean_room", "type": "string" }, "coordinator_reference": { "title": "Optional system or contract reference", "type": "string" }, "created_by_principal": { "title": "`Principal::stable_id()` of the proposer", "type": "string" }, "default_delta": { "format": "decimal", "title": "Required when default_epsilon set and mechanism needs delta", "type": "string" }, "default_epsilon": { "format": "decimal", "title": "Program-level default for DP definitions; null when DP not applicable", "type": "string" }, "default_max_contributor_share": { "format": "decimal", "title": "No participant may dominate output beyond this share (decimal in [0,1])", "type": "string" }, "default_min_properties": { "title": "Hard minimum for cross-tenant outputs", "type": "integer" }, "default_min_subjects": { "title": "Required when output can be person-affecting", "type": "integer" }, "default_min_tenants": { "title": "Hard minimum for cross-tenant outputs (>= 3 for cross_tenant_network)", "type": "integer" }, "default_privacy_mechanisms": { "items": { "enum": [ "cohort_threshold", "contribution_bounding", "differential_privacy", "secure_aggregation", "secure_multiparty_computation", "homomorphic_encryption", "private_set_intersection", "trusted_execution_environment", "manual_statistical_disclosure_control", "none_internal_portfolio_only" ], "type": "string" }, "title": "Default privacy mechanisms applied per definition", "type": "array" }, "description": { "title": "Operator-facing summary. No marketing claims.", "type": "string" }, "display_name": { "title": "Human-readable name", "type": "string" }, "downstream_use_policy": { "title": "Allowed uses for outputs; machine-readable policy can follow later", "type": "string" }, "dpa_reference": { "title": "DPA / consortium-agreement reference. Required for cross-tenant programs unless reviewer waives.", "type": "string" }, "dpia_reference": { "title": "Required for high-risk or person-affecting programs", "type": "string" }, "effective_from": { "format": "date-time", "title": "Effective from", "type": "string" }, "effective_to": { "format": "date-time", "title": "Effective to", "type": "string" }, "governance_tier": { "enum": [ "internal_portfolio", "cross_tenant_network", "consortium_governed", "high_risk_review" ], "title": "Governance tier — floor for cohort / privacy validators", "type": "string" }, "id": { "title": "Program id", "type": "string" }, "legal_basis_summary": { "title": "Bounded summary; full legal document via external ref", "type": "string" }, "minimum_local_runner_version": { "title": "Hard floor — contributions whose `local_runner_version` parses below this semver are rejected at action time (AWS Lambda deprecation floor)", "type": "string" }, "owner_ref": { "title": "Consortium or operator governance reference when owner is not a single tenant", "type": "string" }, "owner_scope": { "enum": [ "tenant", "consortium", "aerandil_managed" ], "title": "Owner scope: tenant / consortium / aerandil_managed", "type": "string" }, "participant_benefit_policy": { "title": "What participating tenants receive in return", "type": "string" }, "privacy_budget_period": { "enum": [ "run", "day", "month", "quarter", "year", "lifetime" ], "title": "Default period for budget accounting", "type": "string" }, "purpose": { "enum": [ "rate_recommendation_calibration", "fraud_signal_calibration", "service_recovery_benchmark", "agent_quality_benchmark", "payment_review_benchmark", "outlet_profitability_benchmark", "energy_water_waste_benchmark", "operations_research", "consortium_standardization", "reviewed_custom" ], "title": "Drives legal / review expectations", "type": "string" }, "recommended_local_runner_version": { "title": "Soft baseline — contributions whose `local_runner_version` parses below this semver emit `contribution_runner_version_outdated_warns` (Stripe-style API-version upgrade signal)", "type": "string" }, "review_gate_policy": { "title": "Names which definitions and outputs require proposal 0020 approval gates (JSON; per-tier required-review map)." }, "status": { "enum": [ "draft", "reviewing", "active", "paused", "deprecated", "retired" ], "title": "Lifecycle status", "type": "string" } }, "required": [ "id", "api_name", "display_name", "owner_scope", "purpose", "status", "governance_tier", "allowed_analysis_kinds", "allowed_output_kinds", "default_min_tenants", "default_min_properties", "default_max_contributor_share", "default_privacy_mechanisms", "privacy_budget_period", "coordinator_kind", "review_gate_policy" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_intelligence_program:read" ] } ], "summary": "Search Federated intelligence program", "tags": [ "federated_intelligence" ] } }, "/v1/object-types/hospitality.federated_output/objects/{id}": { "get": { "description": "Read an existing instance.\n\nAggregate artefact from a federated run. Carries cohort summary, privacy guarantee summary, suppression metadata, confidence intervals where applicable, applicability statement, downstream-use restrictions, and (for model artifacts / signal packages) required model card + datasheet refs. Cross-tenant outputs cannot name tenants or properties unless the program is internal portfolio or a consortium policy explicitly permits named publication (proposal 0021 §4.8 / §7).", "operationId": "get_hospitality_federated_output", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_output" }, "properties": { "additionalProperties": false, "properties": { "applicability_statement": { "title": "What the output can and cannot support", "type": "string" }, "artifact_hash": { "title": "Required when artifact_reference is set", "type": "string" }, "artifact_reference": { "title": "Model artifact, report, or card if stored externally", "type": "string" }, "cohort_summary": { "title": "Buckets; not named participants unless internal portfolio output (JSON)" }, "confidence_intervals": { "title": "Required where output is statistical and meaningful (JSON)" }, "datasheet_reference": { "title": "Required for model artifacts and benchmark exports", "type": "string" }, "downstream_use_restrictions": { "title": "Downstream use restrictions", "type": "string" }, "expires_at": { "format": "date-time", "title": "Required for model artifacts unless waived", "type": "string" }, "id": { "title": "Output id", "type": "string" }, "incident_reference": { "title": "External incident ref when quarantined", "type": "string" }, "metric_values": { "title": "Bounded aggregate values; no row-level data (JSON)" }, "model_card_reference": { "title": "Required for model artifacts and signal packages", "type": "string" }, "noise_parameters": { "title": "Bounded mechanism metadata (JSON)" }, "output_kind": { "enum": [ "benchmark_report", "calibration_curve", "aggregate_metric", "model_artifact", "signal_package", "governance_card" ], "title": "Benchmark report / calibration curve / aggregate metric / model artifact / signal package / governance card", "type": "string" }, "output_schema_version": { "title": "Output schema version", "type": "string" }, "privacy_budget_spend": { "title": "Actual spend (JSON)" }, "privacy_guarantee_summary": { "title": "Mechanisms, epsilon / delta, thresholds, suppression (JSON)" }, "publication_evidence": { "title": "Durable evidence bundle for review gate, budget spend, cohort threshold, suppression, and artifact hash." }, "published_at": { "format": "date-time", "title": "Set by action", "type": "string" }, "published_to_scope": { "enum": [ "program_owner", "participants", "public_aggregate", "specific_recipients" ], "title": "Program owner / participants / public aggregate / specific recipients", "type": "string" }, "quarantine_reason": { "title": "Bounded", "type": "string" }, "quarantined_at": { "format": "date-time", "title": "Set by quarantine action", "type": "string" }, "review_gate_id": { "title": "Required when output review is required", "type": "string" }, "run_id": { "title": "Source run id", "type": "string" }, "status": { "enum": [ "draft", "reviewing", "published", "revoked", "quarantined", "expired" ], "title": "Lifecycle status", "type": "string" }, "suppression_applied": { "title": "True if any metric or slice suppressed", "type": "boolean" }, "suppression_reasons": { "items": { "enum": [ "minimum_tenants_not_met", "minimum_properties_not_met", "minimum_subjects_not_met", "max_contributor_share_exceeded", "privacy_budget_exhausted", "high_variance", "data_quality_mismatch", "legal_basis_missing", "participant_withdrawal", "reviewer_blocked", "security_incident" ], "type": "string" }, "title": "Reasons for suppression", "type": "array" } }, "required": [ "id", "run_id", "output_kind", "status", "output_schema_version", "cohort_summary", "suppression_applied", "suppression_reasons", "applicability_statement", "downstream_use_restrictions", "published_to_scope" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_output:read" ] } ], "summary": "Read Federated output", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.federated_output/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nAggregate artefact from a federated run. Carries cohort summary, privacy guarantee summary, suppression metadata, confidence intervals where applicable, applicability statement, downstream-use restrictions, and (for model artifacts / signal packages) required model card + datasheet refs. Cross-tenant outputs cannot name tenants or properties unless the program is internal portfolio or a consortium policy explicitly permits named publication (proposal 0021 §4.8 / §7).", "operationId": "get_hospitality_federated_output_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.federated_output" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_output:read" ] } ], "summary": "Read Federated output as of a watermark", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.federated_output/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nAggregate artefact from a federated run. Carries cohort summary, privacy guarantee summary, suppression metadata, confidence intervals where applicable, applicability statement, downstream-use restrictions, and (for model artifacts / signal packages) required model card + datasheet refs. Cross-tenant outputs cannot name tenants or properties unless the program is internal portfolio or a consortium policy explicitly permits named publication (proposal 0021 §4.8 / §7).", "operationId": "list_links_hospitality_federated_output", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_output:read" ] } ], "summary": "List links of Federated output", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.approval_gate_for_federated_output", "hospitality.link.federated_output_from_run", "hospitality.link.federated_output_reviewed_by_gate" ] } } ] }, "/v1/object-types/hospitality.federated_output/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nAggregate artefact from a federated run. Carries cohort summary, privacy guarantee summary, suppression metadata, confidence intervals where applicable, applicability statement, downstream-use restrictions, and (for model artifacts / signal packages) required model card + datasheet refs. Cross-tenant outputs cannot name tenants or properties unless the program is internal portfolio or a consortium policy explicitly permits named publication (proposal 0021 §4.8 / §7).", "operationId": "traverse_hospitality_federated_output", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.approval_gate_for_federated_output", "hospitality.link.federated_output_from_run", "hospitality.link.federated_output_reviewed_by_gate" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_output:read" ] } ], "summary": "Traverse from Federated output", "tags": [ "federated_intelligence" ] } }, "/v1/object-types/hospitality.federated_output/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nAggregate artefact from a federated run. Carries cohort summary, privacy guarantee summary, suppression metadata, confidence intervals where applicable, applicability statement, downstream-use restrictions, and (for model artifacts / signal packages) required model card + datasheet refs. Cross-tenant outputs cannot name tenants or properties unless the program is internal portfolio or a consortium policy explicitly permits named publication (proposal 0021 §4.8 / §7).", "operationId": "search_hospitality_federated_output", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "run_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "run_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "run_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "run_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "output_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "benchmark_report", "calibration_curve", "aggregate_metric", "model_artifact", "signal_package", "governance_card" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "draft", "reviewing", "published", "revoked", "quarantined", "expired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "output_schema_version" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "output_schema_version" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "output_schema_version" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "output_schema_version" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "metric_values" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "artifact_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "artifact_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "artifact_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "artifact_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "artifact_hash" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "artifact_hash" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "artifact_hash" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "artifact_hash" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cohort_summary" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "privacy_guarantee_summary" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "privacy_budget_spend" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "suppression_applied" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "suppression_reasons" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "minimum_tenants_not_met", "minimum_properties_not_met", "minimum_subjects_not_met", "max_contributor_share_exceeded", "privacy_budget_exhausted", "high_variance", "data_quality_mismatch", "legal_basis_missing", "participant_withdrawal", "reviewer_blocked", "security_incident" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "noise_parameters" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confidence_intervals" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applicability_statement" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applicability_statement" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "downstream_use_restrictions" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "downstream_use_restrictions" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_card_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_card_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_card_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_card_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "datasheet_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "datasheet_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "datasheet_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "datasheet_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "published_to_scope" }, "type": { "const": "eq" }, "value": { "enum": [ "program_owner", "participants", "public_aggregate", "specific_recipients" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "review_gate_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "review_gate_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "review_gate_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "review_gate_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "publication_evidence" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "published_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "published_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "published_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quarantined_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quarantined_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quarantined_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quarantine_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quarantine_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "incident_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "incident_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "incident_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "incident_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "run_id", "output_kind", "status", "output_schema_version", "artifact_reference", "artifact_hash", "applicability_statement", "downstream_use_restrictions", "model_card_reference", "datasheet_reference", "published_to_scope", "review_gate_id", "published_at", "expires_at", "quarantined_at", "quarantine_reason", "incident_reference" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_output" }, "properties": { "additionalProperties": false, "properties": { "applicability_statement": { "title": "What the output can and cannot support", "type": "string" }, "artifact_hash": { "title": "Required when artifact_reference is set", "type": "string" }, "artifact_reference": { "title": "Model artifact, report, or card if stored externally", "type": "string" }, "cohort_summary": { "title": "Buckets; not named participants unless internal portfolio output (JSON)" }, "confidence_intervals": { "title": "Required where output is statistical and meaningful (JSON)" }, "datasheet_reference": { "title": "Required for model artifacts and benchmark exports", "type": "string" }, "downstream_use_restrictions": { "title": "Downstream use restrictions", "type": "string" }, "expires_at": { "format": "date-time", "title": "Required for model artifacts unless waived", "type": "string" }, "id": { "title": "Output id", "type": "string" }, "incident_reference": { "title": "External incident ref when quarantined", "type": "string" }, "metric_values": { "title": "Bounded aggregate values; no row-level data (JSON)" }, "model_card_reference": { "title": "Required for model artifacts and signal packages", "type": "string" }, "noise_parameters": { "title": "Bounded mechanism metadata (JSON)" }, "output_kind": { "enum": [ "benchmark_report", "calibration_curve", "aggregate_metric", "model_artifact", "signal_package", "governance_card" ], "title": "Benchmark report / calibration curve / aggregate metric / model artifact / signal package / governance card", "type": "string" }, "output_schema_version": { "title": "Output schema version", "type": "string" }, "privacy_budget_spend": { "title": "Actual spend (JSON)" }, "privacy_guarantee_summary": { "title": "Mechanisms, epsilon / delta, thresholds, suppression (JSON)" }, "publication_evidence": { "title": "Durable evidence bundle for review gate, budget spend, cohort threshold, suppression, and artifact hash." }, "published_at": { "format": "date-time", "title": "Set by action", "type": "string" }, "published_to_scope": { "enum": [ "program_owner", "participants", "public_aggregate", "specific_recipients" ], "title": "Program owner / participants / public aggregate / specific recipients", "type": "string" }, "quarantine_reason": { "title": "Bounded", "type": "string" }, "quarantined_at": { "format": "date-time", "title": "Set by quarantine action", "type": "string" }, "review_gate_id": { "title": "Required when output review is required", "type": "string" }, "run_id": { "title": "Source run id", "type": "string" }, "status": { "enum": [ "draft", "reviewing", "published", "revoked", "quarantined", "expired" ], "title": "Lifecycle status", "type": "string" }, "suppression_applied": { "title": "True if any metric or slice suppressed", "type": "boolean" }, "suppression_reasons": { "items": { "enum": [ "minimum_tenants_not_met", "minimum_properties_not_met", "minimum_subjects_not_met", "max_contributor_share_exceeded", "privacy_budget_exhausted", "high_variance", "data_quality_mismatch", "legal_basis_missing", "participant_withdrawal", "reviewer_blocked", "security_incident" ], "type": "string" }, "title": "Reasons for suppression", "type": "array" } }, "required": [ "id", "run_id", "output_kind", "status", "output_schema_version", "cohort_summary", "suppression_applied", "suppression_reasons", "applicability_statement", "downstream_use_restrictions", "published_to_scope" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_output:read" ] } ], "summary": "Search Federated output", "tags": [ "federated_intelligence" ] } }, "/v1/object-types/hospitality.federated_participation/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOpt-in / opt-out record for a tenant, property, portfolio, or venue participating in a program. Carries legal basis, DPA / consent references, allowed analysis kinds, participation- specific exclusions, local execution mode, agent installation reference (when execution mode is agent_installation), credential reference (opaque), optional participant-level contribution cap, output access tier, and prospective withdrawal status. Withdrawal excludes future runs after `withdrawal_effective_at`; already published outputs remain unless quarantined by review (proposal 0021 §4.4 / §10.6).", "operationId": "get_hospitality_federated_participation", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_participation" }, "properties": { "additionalProperties": false, "properties": { "agent_installation_id": { "title": "Required when execution mode is agent_installation", "type": "string" }, "allowed_analysis_kinds": { "items": { "enum": [ "federated_analytics", "federated_learning", "private_set_intersection", "clean_room_query", "benchmark_export" ], "type": "string" }, "title": "Participant may opt into analytics but not model training", "type": "array" }, "approved_by_principal": { "title": "Required for active cross-tenant participation", "type": "string" }, "consent_policy_reference": { "title": "Required if consent is the basis", "type": "string" }, "contribution_weight_cap": { "format": "decimal", "title": "Participant-specific cap stricter than definition (decimal in [0,1])", "type": "string" }, "credential_reference": { "title": "Pointer to operator vault or clean-room credential. No secret material — same `credential_reference_no_secret_material` discipline as proposal 0020.", "type": "string" }, "dispatch_endpoint_url": { "title": "Participant-published HTTPS URL the proposal 0022 dispatcher POSTs signed envelopes to (§6.1). Absent for SSE-only / pull-based profiles — the dispatcher terminal-fails push dispatches to a participation without one. HTTPS-only; http is admissible solely for loopback receivers (local development), mirroring the webhook-subscription rule.", "type": "string" }, "dpa_reference": { "title": "Required for cross-tenant programs", "type": "string" }, "enrolled_by_principal": { "title": "Principal stable id of enroller (human or admin agent)", "type": "string" }, "excluded_field_classes": { "items": { "type": "string" }, "title": "Additional local privacy exclusions", "type": "array" }, "excluded_object_types": { "items": { "type": "string" }, "title": "Tenant-specific exclusions", "type": "array" }, "id": { "title": "Participation id", "type": "string" }, "legal_basis_kind": { "enum": [ "contract", "legitimate_interest", "consent", "public_task", "not_personal_data", "other_reviewed" ], "title": "Contract / legitimate_interest / consent / public_task / not_personal_data / other_reviewed", "type": "string" }, "legal_basis_reference": { "title": "Required except for not_personal_data with reviewer note", "type": "string" }, "local_execution_mode": { "enum": [ "operator_runner", "agent_installation", "hosted_connector", "third_party_clean_room" ], "title": "How local extraction runs", "type": "string" }, "output_access_level": { "enum": [ "none", "aggregate_only", "participant_benchmark", "model_consumer" ], "title": "Output-access tier granted to this participant", "type": "string" }, "participant_object_ref": { "title": "Property / venue / portfolio id when scope is not tenant. The concrete typed link lives on the link surface for property and venue scopes (proposal §6).", "type": "string" }, "participant_scope": { "enum": [ "tenant", "property", "portfolio", "venue" ], "title": "Tenant / property / portfolio / venue", "type": "string" }, "privacy_budget_account_id": { "title": "Optional explicit budget account", "type": "string" }, "program_api_name": { "title": "Program joined", "type": "string" }, "runner_identity_ref": { "title": "SPIFFE URI or other identity URI for the runner; matched against the envelope's `participant.runner_identity_ref` at dispatch time (proposal 0022 §8.3).", "type": "string" }, "runner_signing_key_ref": { "title": "Opaque pointer to the runner's Ed25519 verification key in the operator's vault. No key material stored here per `credential_reference_no_secret_material` (proposal 0022 §8.2).", "type": "string" }, "status": { "enum": [ "invited", "reviewing", "active", "paused", "withdrawn", "revoked" ], "title": "Lifecycle status", "type": "string" }, "withdrawal_effective_at": { "format": "date-time", "title": "Prospective exclusion point", "type": "string" }, "withdrawal_reason": { "title": "Withdrawal reason", "type": "string" }, "withdrawal_requested_at": { "format": "date-time", "title": "Set when participant withdraws", "type": "string" } }, "required": [ "id", "program_api_name", "participant_scope", "status", "legal_basis_kind", "allowed_analysis_kinds", "excluded_object_types", "excluded_field_classes", "local_execution_mode", "output_access_level" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_participation:read" ] } ], "summary": "Read Federated participation", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.federated_participation/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOpt-in / opt-out record for a tenant, property, portfolio, or venue participating in a program. Carries legal basis, DPA / consent references, allowed analysis kinds, participation- specific exclusions, local execution mode, agent installation reference (when execution mode is agent_installation), credential reference (opaque), optional participant-level contribution cap, output access tier, and prospective withdrawal status. Withdrawal excludes future runs after `withdrawal_effective_at`; already published outputs remain unless quarantined by review (proposal 0021 §4.4 / §10.6).", "operationId": "get_hospitality_federated_participation_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.federated_participation" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_participation:read" ] } ], "summary": "Read Federated participation as of a watermark", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.federated_participation/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOpt-in / opt-out record for a tenant, property, portfolio, or venue participating in a program. Carries legal basis, DPA / consent references, allowed analysis kinds, participation- specific exclusions, local execution mode, agent installation reference (when execution mode is agent_installation), credential reference (opaque), optional participant-level contribution cap, output access tier, and prospective withdrawal status. Withdrawal excludes future runs after `withdrawal_effective_at`; already published outputs remain unless quarantined by review (proposal 0021 §4.4 / §10.6).", "operationId": "list_links_hospitality_federated_participation", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_participation:read" ] } ], "summary": "List links of Federated participation", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.federated_contribution_from_participation", "hospitality.link.federated_local_runner_agent_installation", "hospitality.link.federated_participation_for_property", "hospitality.link.federated_participation_for_venue", "hospitality.link.federated_participation_in_program", "hospitality.link.privacy_budget_for_participation" ] } } ] }, "/v1/object-types/hospitality.federated_participation/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOpt-in / opt-out record for a tenant, property, portfolio, or venue participating in a program. Carries legal basis, DPA / consent references, allowed analysis kinds, participation- specific exclusions, local execution mode, agent installation reference (when execution mode is agent_installation), credential reference (opaque), optional participant-level contribution cap, output access tier, and prospective withdrawal status. Withdrawal excludes future runs after `withdrawal_effective_at`; already published outputs remain unless quarantined by review (proposal 0021 §4.4 / §10.6).", "operationId": "traverse_hospitality_federated_participation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.federated_contribution_from_participation", "hospitality.link.federated_local_runner_agent_installation", "hospitality.link.federated_participation_for_property", "hospitality.link.federated_participation_for_venue", "hospitality.link.federated_participation_in_program", "hospitality.link.privacy_budget_for_participation" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_participation:read" ] } ], "summary": "Traverse from Federated participation", "tags": [ "federated_intelligence" ] } }, "/v1/object-types/hospitality.federated_participation/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOpt-in / opt-out record for a tenant, property, portfolio, or venue participating in a program. Carries legal basis, DPA / consent references, allowed analysis kinds, participation- specific exclusions, local execution mode, agent installation reference (when execution mode is agent_installation), credential reference (opaque), optional participant-level contribution cap, output access tier, and prospective withdrawal status. Withdrawal excludes future runs after `withdrawal_effective_at`; already published outputs remain unless quarantined by review (proposal 0021 §4.4 / §10.6).", "operationId": "search_hospitality_federated_participation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "program_api_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "program_api_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "program_api_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "program_api_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "participant_scope" }, "type": { "const": "eq" }, "value": { "enum": [ "tenant", "property", "portfolio", "venue" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "participant_object_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "participant_object_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "participant_object_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "participant_object_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "invited", "reviewing", "active", "paused", "withdrawn", "revoked" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "enrolled_by_principal" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "enrolled_by_principal" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "enrolled_by_principal" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "enrolled_by_principal" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approved_by_principal" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approved_by_principal" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approved_by_principal" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "approved_by_principal" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "legal_basis_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "contract", "legitimate_interest", "consent", "public_task", "not_personal_data", "other_reviewed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "legal_basis_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "legal_basis_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "legal_basis_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "legal_basis_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dpa_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dpa_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dpa_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dpa_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "consent_policy_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "consent_policy_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "consent_policy_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "consent_policy_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "allowed_analysis_kinds" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "federated_analytics", "federated_learning", "private_set_intersection", "clean_room_query", "benchmark_export" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "excluded_object_types" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "excluded_field_classes" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "local_execution_mode" }, "type": { "const": "eq" }, "value": { "enum": [ "operator_runner", "agent_installation", "hosted_connector", "third_party_clean_room" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_installation_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_installation_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_installation_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_installation_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "credential_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "credential_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "credential_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "credential_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "privacy_budget_account_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "privacy_budget_account_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "privacy_budget_account_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "privacy_budget_account_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contribution_weight_cap" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contribution_weight_cap" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contribution_weight_cap" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "output_access_level" }, "type": { "const": "eq" }, "value": { "enum": [ "none", "aggregate_only", "participant_benchmark", "model_consumer" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "withdrawal_requested_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "withdrawal_requested_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "withdrawal_requested_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "withdrawal_effective_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "withdrawal_effective_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "withdrawal_effective_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "withdrawal_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "withdrawal_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "runner_identity_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "runner_identity_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "runner_identity_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "runner_identity_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "runner_signing_key_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "runner_signing_key_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "runner_signing_key_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "runner_signing_key_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispatch_endpoint_url" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispatch_endpoint_url" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispatch_endpoint_url" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispatch_endpoint_url" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "program_api_name", "participant_scope", "participant_object_ref", "status", "enrolled_by_principal", "approved_by_principal", "legal_basis_kind", "legal_basis_reference", "dpa_reference", "consent_policy_reference", "local_execution_mode", "agent_installation_id", "credential_reference", "privacy_budget_account_id", "contribution_weight_cap", "output_access_level", "withdrawal_requested_at", "withdrawal_effective_at", "withdrawal_reason", "runner_identity_ref", "runner_signing_key_ref", "dispatch_endpoint_url" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_participation" }, "properties": { "additionalProperties": false, "properties": { "agent_installation_id": { "title": "Required when execution mode is agent_installation", "type": "string" }, "allowed_analysis_kinds": { "items": { "enum": [ "federated_analytics", "federated_learning", "private_set_intersection", "clean_room_query", "benchmark_export" ], "type": "string" }, "title": "Participant may opt into analytics but not model training", "type": "array" }, "approved_by_principal": { "title": "Required for active cross-tenant participation", "type": "string" }, "consent_policy_reference": { "title": "Required if consent is the basis", "type": "string" }, "contribution_weight_cap": { "format": "decimal", "title": "Participant-specific cap stricter than definition (decimal in [0,1])", "type": "string" }, "credential_reference": { "title": "Pointer to operator vault or clean-room credential. No secret material — same `credential_reference_no_secret_material` discipline as proposal 0020.", "type": "string" }, "dispatch_endpoint_url": { "title": "Participant-published HTTPS URL the proposal 0022 dispatcher POSTs signed envelopes to (§6.1). Absent for SSE-only / pull-based profiles — the dispatcher terminal-fails push dispatches to a participation without one. HTTPS-only; http is admissible solely for loopback receivers (local development), mirroring the webhook-subscription rule.", "type": "string" }, "dpa_reference": { "title": "Required for cross-tenant programs", "type": "string" }, "enrolled_by_principal": { "title": "Principal stable id of enroller (human or admin agent)", "type": "string" }, "excluded_field_classes": { "items": { "type": "string" }, "title": "Additional local privacy exclusions", "type": "array" }, "excluded_object_types": { "items": { "type": "string" }, "title": "Tenant-specific exclusions", "type": "array" }, "id": { "title": "Participation id", "type": "string" }, "legal_basis_kind": { "enum": [ "contract", "legitimate_interest", "consent", "public_task", "not_personal_data", "other_reviewed" ], "title": "Contract / legitimate_interest / consent / public_task / not_personal_data / other_reviewed", "type": "string" }, "legal_basis_reference": { "title": "Required except for not_personal_data with reviewer note", "type": "string" }, "local_execution_mode": { "enum": [ "operator_runner", "agent_installation", "hosted_connector", "third_party_clean_room" ], "title": "How local extraction runs", "type": "string" }, "output_access_level": { "enum": [ "none", "aggregate_only", "participant_benchmark", "model_consumer" ], "title": "Output-access tier granted to this participant", "type": "string" }, "participant_object_ref": { "title": "Property / venue / portfolio id when scope is not tenant. The concrete typed link lives on the link surface for property and venue scopes (proposal §6).", "type": "string" }, "participant_scope": { "enum": [ "tenant", "property", "portfolio", "venue" ], "title": "Tenant / property / portfolio / venue", "type": "string" }, "privacy_budget_account_id": { "title": "Optional explicit budget account", "type": "string" }, "program_api_name": { "title": "Program joined", "type": "string" }, "runner_identity_ref": { "title": "SPIFFE URI or other identity URI for the runner; matched against the envelope's `participant.runner_identity_ref` at dispatch time (proposal 0022 §8.3).", "type": "string" }, "runner_signing_key_ref": { "title": "Opaque pointer to the runner's Ed25519 verification key in the operator's vault. No key material stored here per `credential_reference_no_secret_material` (proposal 0022 §8.2).", "type": "string" }, "status": { "enum": [ "invited", "reviewing", "active", "paused", "withdrawn", "revoked" ], "title": "Lifecycle status", "type": "string" }, "withdrawal_effective_at": { "format": "date-time", "title": "Prospective exclusion point", "type": "string" }, "withdrawal_reason": { "title": "Withdrawal reason", "type": "string" }, "withdrawal_requested_at": { "format": "date-time", "title": "Set when participant withdraws", "type": "string" } }, "required": [ "id", "program_api_name", "participant_scope", "status", "legal_basis_kind", "allowed_analysis_kinds", "excluded_object_types", "excluded_field_classes", "local_execution_mode", "output_access_level" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_participation:read" ] } ], "summary": "Search Federated participation", "tags": [ "federated_intelligence" ] } }, "/v1/object-types/hospitality.federated_run/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne execution of an approved analysis definition against a cohort and time window. Pins the definition version, freezes the cohort snapshot and input window, reserves privacy budget, and drives the §5.11 lifecycle. Idempotent on `run_key`; retries with identical parameters return the existing run, retries with different parameters reject as idempotency mismatch (proposal 0021 §4.6 / §9).", "operationId": "get_hospitality_federated_run", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_run" }, "properties": { "additionalProperties": false, "properties": { "aggregation_protocol": { "enum": [ "plain_aggregate_reviewed", "secure_aggregation", "clean_room_dp", "external_protocol" ], "title": "Aggregation protocol", "type": "string" }, "ci_width_warn_threshold": { "format": "decimal", "title": "Snapshot of the definition's maximum acceptable confidence-interval width at run start.", "type": "string" }, "clean_room_job_ref": { "title": "Required for third-party clean room", "type": "string" }, "cohort_id": { "title": "Federated cohort definition object id. Part of the durable idempotency key.", "type": "string" }, "cohort_snapshot": { "title": "Frozen cohort rules and threshold settings (JSON)" }, "correlation_id": { "title": "Ties events together", "type": "string" }, "deadline_at": { "format": "date-time", "title": "Contribution deadline", "type": "string" }, "definition_api_name": { "title": "Definition api name", "type": "string" }, "definition_id": { "title": "Federated analysis definition object id. Part of the durable idempotency key.", "type": "string" }, "definition_version": { "title": "Frozen at start", "type": "string" }, "failure_reason": { "title": "Bounded", "type": "string" }, "finished_at": { "format": "date-time", "title": "Set by aggregation result", "type": "string" }, "id": { "title": "Run id", "type": "string" }, "input_window_end": { "format": "date-time", "title": "Input window end", "type": "string" }, "input_window_start": { "format": "date-time", "title": "Input window start", "type": "string" }, "metric_warn_thresholds": { "title": "Snapshot of the definition's per-metric minimum acceptable validation values at run start (JSON map)." }, "participants_expected": { "title": "Count at run start", "type": "integer" }, "participants_requested": { "title": "Count after eligibility checks", "type": "integer" }, "participants_submitted": { "title": "Count accepted before aggregation", "type": "integer" }, "participants_suppressed": { "title": "Count suppressed / rejected", "type": "integer" }, "privacy_budget_reserved": { "title": "Epsilon / delta / account refs reserved for the run (JSON)" }, "program_api_name": { "title": "Program api name", "type": "string" }, "request_fingerprint": { "title": "SHA-256 over canonical run-start request fields. Same run_key with a different fingerprint is rejected.", "type": "string" }, "run_key": { "title": "Stable idempotency key: program + definition + version + cohort + window", "type": "string" }, "secure_aggregation_session_ref": { "title": "Required for secure aggregation", "type": "string" }, "started_at": { "format": "date-time", "title": "Set by action", "type": "string" }, "status": { "enum": [ "queued", "privacy_review", "approved", "collecting", "aggregating", "output_review", "completed", "failed", "cancelled", "quarantined" ], "title": "Lifecycle status", "type": "string" }, "trigger_kind": { "enum": [ "scheduled", "manual", "workflow", "agent_request", "backfill" ], "title": "Scheduled / manual / workflow / agent / backfill", "type": "string" } }, "required": [ "id", "program_api_name", "definition_api_name", "definition_id", "definition_version", "cohort_id", "run_key", "status", "trigger_kind", "cohort_snapshot", "input_window_start", "input_window_end", "request_fingerprint", "participants_expected", "participants_requested", "participants_submitted", "participants_suppressed", "aggregation_protocol", "correlation_id" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_run:read" ] } ], "summary": "Read Federated run", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.federated_run/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne execution of an approved analysis definition against a cohort and time window. Pins the definition version, freezes the cohort snapshot and input window, reserves privacy budget, and drives the §5.11 lifecycle. Idempotent on `run_key`; retries with identical parameters return the existing run, retries with different parameters reject as idempotency mismatch (proposal 0021 §4.6 / §9).", "operationId": "get_hospitality_federated_run_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.federated_run" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_run:read" ] } ], "summary": "Read Federated run as of a watermark", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.federated_run/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne execution of an approved analysis definition against a cohort and time window. Pins the definition version, freezes the cohort snapshot and input window, reserves privacy budget, and drives the §5.11 lifecycle. Idempotent on `run_key`; retries with identical parameters return the existing run, retries with different parameters reject as idempotency mismatch (proposal 0021 §4.6 / §9).", "operationId": "list_links_hospitality_federated_run", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_run:read" ] } ], "summary": "List links of Federated run", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.federated_contribution_for_run", "hospitality.link.federated_output_from_run", "hospitality.link.federated_run_reserved_from_account", "hospitality.link.federated_run_started_by_workflow", "hospitality.link.federated_run_uses_cohort", "hospitality.link.federated_run_uses_definition", "hospitality.link.participant_dispatch_for_run" ] } } ] }, "/v1/object-types/hospitality.federated_run/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne execution of an approved analysis definition against a cohort and time window. Pins the definition version, freezes the cohort snapshot and input window, reserves privacy budget, and drives the §5.11 lifecycle. Idempotent on `run_key`; retries with identical parameters return the existing run, retries with different parameters reject as idempotency mismatch (proposal 0021 §4.6 / §9).", "operationId": "traverse_hospitality_federated_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.federated_contribution_for_run", "hospitality.link.federated_output_from_run", "hospitality.link.federated_run_reserved_from_account", "hospitality.link.federated_run_started_by_workflow", "hospitality.link.federated_run_uses_cohort", "hospitality.link.federated_run_uses_definition", "hospitality.link.participant_dispatch_for_run" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_run:read" ] } ], "summary": "Traverse from Federated run", "tags": [ "federated_intelligence" ] } }, "/v1/object-types/hospitality.federated_run/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne execution of an approved analysis definition against a cohort and time window. Pins the definition version, freezes the cohort snapshot and input window, reserves privacy budget, and drives the §5.11 lifecycle. Idempotent on `run_key`; retries with identical parameters return the existing run, retries with different parameters reject as idempotency mismatch (proposal 0021 §4.6 / §9).", "operationId": "search_hospitality_federated_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "program_api_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "program_api_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "program_api_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "program_api_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_api_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_api_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_api_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_api_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_version" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_version" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_version" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_version" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cohort_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cohort_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cohort_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cohort_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "run_key" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "run_key" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "run_key" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "run_key" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "queued", "privacy_review", "approved", "collecting", "aggregating", "output_review", "completed", "failed", "cancelled", "quarantined" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "trigger_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "scheduled", "manual", "workflow", "agent_request", "backfill" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cohort_snapshot" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "input_window_start" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "input_window_start" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "input_window_start" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "input_window_end" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "input_window_end" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "input_window_end" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "request_fingerprint" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "request_fingerprint" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "request_fingerprint" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "request_fingerprint" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "participants_expected" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "participants_expected" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "participants_expected" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "participants_requested" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "participants_requested" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "participants_requested" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "participants_submitted" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "participants_submitted" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "participants_submitted" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "participants_suppressed" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "participants_suppressed" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "participants_suppressed" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "privacy_budget_reserved" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "metric_warn_thresholds" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ci_width_warn_threshold" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ci_width_warn_threshold" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ci_width_warn_threshold" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "aggregation_protocol" }, "type": { "const": "eq" }, "value": { "enum": [ "plain_aggregate_reviewed", "secure_aggregation", "clean_room_dp", "external_protocol" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "secure_aggregation_session_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "secure_aggregation_session_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "secure_aggregation_session_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "secure_aggregation_session_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "clean_room_job_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "clean_room_job_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "clean_room_job_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "clean_room_job_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "deadline_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "deadline_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "deadline_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "finished_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "finished_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "finished_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "failure_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "failure_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "correlation_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "correlation_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "correlation_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "correlation_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "program_api_name", "definition_api_name", "definition_id", "definition_version", "cohort_id", "run_key", "status", "trigger_kind", "input_window_start", "input_window_end", "request_fingerprint", "participants_expected", "participants_requested", "participants_submitted", "participants_suppressed", "ci_width_warn_threshold", "aggregation_protocol", "secure_aggregation_session_ref", "clean_room_job_ref", "deadline_at", "started_at", "finished_at", "failure_reason", "correlation_id" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.federated_run" }, "properties": { "additionalProperties": false, "properties": { "aggregation_protocol": { "enum": [ "plain_aggregate_reviewed", "secure_aggregation", "clean_room_dp", "external_protocol" ], "title": "Aggregation protocol", "type": "string" }, "ci_width_warn_threshold": { "format": "decimal", "title": "Snapshot of the definition's maximum acceptable confidence-interval width at run start.", "type": "string" }, "clean_room_job_ref": { "title": "Required for third-party clean room", "type": "string" }, "cohort_id": { "title": "Federated cohort definition object id. Part of the durable idempotency key.", "type": "string" }, "cohort_snapshot": { "title": "Frozen cohort rules and threshold settings (JSON)" }, "correlation_id": { "title": "Ties events together", "type": "string" }, "deadline_at": { "format": "date-time", "title": "Contribution deadline", "type": "string" }, "definition_api_name": { "title": "Definition api name", "type": "string" }, "definition_id": { "title": "Federated analysis definition object id. Part of the durable idempotency key.", "type": "string" }, "definition_version": { "title": "Frozen at start", "type": "string" }, "failure_reason": { "title": "Bounded", "type": "string" }, "finished_at": { "format": "date-time", "title": "Set by aggregation result", "type": "string" }, "id": { "title": "Run id", "type": "string" }, "input_window_end": { "format": "date-time", "title": "Input window end", "type": "string" }, "input_window_start": { "format": "date-time", "title": "Input window start", "type": "string" }, "metric_warn_thresholds": { "title": "Snapshot of the definition's per-metric minimum acceptable validation values at run start (JSON map)." }, "participants_expected": { "title": "Count at run start", "type": "integer" }, "participants_requested": { "title": "Count after eligibility checks", "type": "integer" }, "participants_submitted": { "title": "Count accepted before aggregation", "type": "integer" }, "participants_suppressed": { "title": "Count suppressed / rejected", "type": "integer" }, "privacy_budget_reserved": { "title": "Epsilon / delta / account refs reserved for the run (JSON)" }, "program_api_name": { "title": "Program api name", "type": "string" }, "request_fingerprint": { "title": "SHA-256 over canonical run-start request fields. Same run_key with a different fingerprint is rejected.", "type": "string" }, "run_key": { "title": "Stable idempotency key: program + definition + version + cohort + window", "type": "string" }, "secure_aggregation_session_ref": { "title": "Required for secure aggregation", "type": "string" }, "started_at": { "format": "date-time", "title": "Set by action", "type": "string" }, "status": { "enum": [ "queued", "privacy_review", "approved", "collecting", "aggregating", "output_review", "completed", "failed", "cancelled", "quarantined" ], "title": "Lifecycle status", "type": "string" }, "trigger_kind": { "enum": [ "scheduled", "manual", "workflow", "agent_request", "backfill" ], "title": "Scheduled / manual / workflow / agent / backfill", "type": "string" } }, "required": [ "id", "program_api_name", "definition_api_name", "definition_id", "definition_version", "cohort_id", "run_key", "status", "trigger_kind", "cohort_snapshot", "input_window_start", "input_window_end", "request_fingerprint", "participants_expected", "participants_requested", "participants_submitted", "participants_suppressed", "aggregation_protocol", "correlation_id" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.federated_run:read" ] } ], "summary": "Search Federated run", "tags": [ "federated_intelligence" ] } }, "/v1/object-types/hospitality.feedback_label/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne of a house's guest-feedback labels — hubOS's quality labels: a `code` and a `name` the house files feedback under (\"breakfast\", \"noise at night\", \"VIP\"), beside the kernel's fixed `category`. Keyed by `code` within the house (`feedback_label_at_property`); `define_feedback_label` with a code the house holds re-states it in place. `active` labels are put on feedback by `set_guest_feedback_labels`; a `retired` one stays on the feedback it was put on and goes on no more, and re-stating its code revives it.", "operationId": "get_hospitality_feedback_label", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.feedback_label" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "The house's code for the label — unique within the house", "type": "string" }, "defined_at": { "format": "date-time", "title": "When it was first defined", "type": "string" }, "name": { "title": "The label in words, as the desk and the floor read it", "type": "string" }, "retired_at": { "format": "date-time", "title": "When it was retired", "type": "string" }, "status": { "enum": [ "active", "retired" ], "title": "Active (put on feedback) or retired", "type": "string" } }, "required": [ "code", "name", "status", "defined_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.feedback_label:read" ] } ], "summary": "Read Feedback label", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.feedback_label/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne of a house's guest-feedback labels — hubOS's quality labels: a `code` and a `name` the house files feedback under (\"breakfast\", \"noise at night\", \"VIP\"), beside the kernel's fixed `category`. Keyed by `code` within the house (`feedback_label_at_property`); `define_feedback_label` with a code the house holds re-states it in place. `active` labels are put on feedback by `set_guest_feedback_labels`; a `retired` one stays on the feedback it was put on and goes on no more, and re-stating its code revives it.", "operationId": "get_hospitality_feedback_label_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.feedback_label" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.feedback_label:read" ] } ], "summary": "Read Feedback label as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.feedback_label/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne of a house's guest-feedback labels — hubOS's quality labels: a `code` and a `name` the house files feedback under (\"breakfast\", \"noise at night\", \"VIP\"), beside the kernel's fixed `category`. Keyed by `code` within the house (`feedback_label_at_property`); `define_feedback_label` with a code the house holds re-states it in place. `active` labels are put on feedback by `set_guest_feedback_labels`; a `retired` one stays on the feedback it was put on and goes on no more, and re-stating its code revives it.", "operationId": "list_links_hospitality_feedback_label", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.feedback_label:read" ] } ], "summary": "List links of Feedback label", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.feedback_label_at_property", "hospitality.link.guest_feedback_has_label" ] } } ] }, "/v1/object-types/hospitality.feedback_label/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne of a house's guest-feedback labels — hubOS's quality labels: a `code` and a `name` the house files feedback under (\"breakfast\", \"noise at night\", \"VIP\"), beside the kernel's fixed `category`. Keyed by `code` within the house (`feedback_label_at_property`); `define_feedback_label` with a code the house holds re-states it in place. `active` labels are put on feedback by `set_guest_feedback_labels`; a `retired` one stays on the feedback it was put on and goes on no more, and re-stating its code revives it.", "operationId": "traverse_hospitality_feedback_label", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.feedback_label_at_property", "hospitality.link.guest_feedback_has_label" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.feedback_label:read" ] } ], "summary": "Traverse from Feedback label", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.feedback_label/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne of a house's guest-feedback labels — hubOS's quality labels: a `code` and a `name` the house files feedback under (\"breakfast\", \"noise at night\", \"VIP\"), beside the kernel's fixed `category`. Keyed by `code` within the house (`feedback_label_at_property`); `define_feedback_label` with a code the house holds re-states it in place. `active` labels are put on feedback by `set_guest_feedback_labels`; a `retired` one stays on the feedback it was put on and goes on no more, and re-stating its code revives it.", "operationId": "search_hospitality_feedback_label", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "retired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "defined_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "defined_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "defined_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "status", "defined_at", "retired_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.feedback_label" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "The house's code for the label — unique within the house", "type": "string" }, "defined_at": { "format": "date-time", "title": "When it was first defined", "type": "string" }, "name": { "title": "The label in words, as the desk and the floor read it", "type": "string" }, "retired_at": { "format": "date-time", "title": "When it was retired", "type": "string" }, "status": { "enum": [ "active", "retired" ], "title": "Active (put on feedback) or retired", "type": "string" } }, "required": [ "code", "name", "status", "defined_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.feedback_label:read" ] } ], "summary": "Search Feedback label", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.folio/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe accounting ledger for a stay. Holds charges and payments; closes when the guest checks out and the balance is zero.", "operationId": "get_hospitality_folio", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" }, "properties": { "additionalProperties": false, "properties": { "ar_aging_bucket": { "enum": [ "current", "30_days", "60_days", "90_days", "120_plus" ], "title": "A/R aging bucket (projection)", "type": "string" }, "ar_transferred_at": { "format": "date-time", "title": "When folio settled to company A/R", "type": "string" }, "balance": { "description": "Outstanding balance", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Folio balance", "type": "object" }, "balance_forward": { "description": "Balance brought forward onto the ledger", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Folio balance forward", "type": "object" }, "closed_at": { "format": "date-time", "title": "Closed at", "type": "string" }, "due_at": { "format": "date-time", "title": "Payment due at", "type": "string" }, "external_invoice_number": { "title": "Operator-facing invoice number", "type": "string" }, "kind": { "enum": [ "guest", "master", "group_master", "company_ar", "house", "comp", "rebate" ], "title": "Folio kind", "type": "string" }, "number": { "title": "Folio number", "type": "string" }, "opened_at": { "format": "date-time", "title": "Opened at", "type": "string" }, "reopened_at": { "format": "date-time", "title": "Reopened at", "type": "string" }, "status": { "enum": [ "open", "closed", "void" ], "title": "Folio status", "type": "string" }, "window_number": { "title": "Window number (1..=8)", "type": "integer" } }, "required": [ "number", "status", "kind", "window_number", "balance", "opened_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.folio:read" ] } ], "summary": "Read Folio", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.folio/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe accounting ledger for a stay. Holds charges and payments; closes when the guest checks out and the balance is zero.", "operationId": "get_hospitality_folio_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.folio" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.folio:read" ] } ], "summary": "Read Folio as of a watermark", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.folio/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe accounting ledger for a stay. Holds charges and payments; closes when the guest checks out and the balance is zero.", "operationId": "list_links_hospitality_folio", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.folio:read" ] } ], "summary": "List links of Folio", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.appointment_settled_to_folio", "hospitality.link.banquet_order_posts_to_folio", "hospitality.link.block_has_master_folio", "hospitality.link.check_payment_to_folio", "hospitality.link.check_settled_to_folio", "hospitality.link.company_has_ar_folio", "hospitality.link.folio_has_charge", "hospitality.link.folio_has_payment", "hospitality.link.folio_part_of_group_master", "hospitality.link.folio_rebates_folio", "hospitality.link.folio_routes_to_master_folio", "hospitality.link.folio_routing_rule_source", "hospitality.link.folio_routing_rule_target", "hospitality.link.folio_settled_by_company_ar", "hospitality.link.invoice_for_folio", "hospitality.link.reservation_has_folio", "hospitality.link.stay_has_folio", "hospitality.link.workflow_run_targets_folio" ] } } ] }, "/v1/object-types/hospitality.folio/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe accounting ledger for a stay. Holds charges and payments; closes when the guest checks out and the balance is zero.", "operationId": "traverse_hospitality_folio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.appointment_settled_to_folio", "hospitality.link.banquet_order_posts_to_folio", "hospitality.link.block_has_master_folio", "hospitality.link.check_payment_to_folio", "hospitality.link.check_settled_to_folio", "hospitality.link.company_has_ar_folio", "hospitality.link.folio_has_charge", "hospitality.link.folio_has_payment", "hospitality.link.folio_part_of_group_master", "hospitality.link.folio_rebates_folio", "hospitality.link.folio_routes_to_master_folio", "hospitality.link.folio_routing_rule_source", "hospitality.link.folio_routing_rule_target", "hospitality.link.folio_settled_by_company_ar", "hospitality.link.invoice_for_folio", "hospitality.link.reservation_has_folio", "hospitality.link.stay_has_folio", "hospitality.link.workflow_run_targets_folio" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.folio:read" ] } ], "summary": "Traverse from Folio", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.folio/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe accounting ledger for a stay. Holds charges and payments; closes when the guest checks out and the balance is zero.", "operationId": "search_hospitality_folio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "number" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "number" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "number" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "number" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "open", "closed", "void" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "guest", "master", "group_master", "company_ar", "house", "comp", "rebate" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "window_number" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "window_number" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "window_number" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "balance" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "balance_forward" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reopened_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reopened_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reopened_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_invoice_number" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_invoice_number" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_invoice_number" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_invoice_number" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ar_aging_bucket" }, "type": { "const": "eq" }, "value": { "enum": [ "current", "30_days", "60_days", "90_days", "120_plus" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ar_transferred_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ar_transferred_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ar_transferred_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "due_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "due_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "due_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "number", "status", "kind", "window_number", "opened_at", "closed_at", "reopened_at", "external_invoice_number", "ar_aging_bucket", "ar_transferred_at", "due_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio" }, "properties": { "additionalProperties": false, "properties": { "ar_aging_bucket": { "enum": [ "current", "30_days", "60_days", "90_days", "120_plus" ], "title": "A/R aging bucket (projection)", "type": "string" }, "ar_transferred_at": { "format": "date-time", "title": "When folio settled to company A/R", "type": "string" }, "balance": { "description": "Outstanding balance", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Folio balance", "type": "object" }, "balance_forward": { "description": "Balance brought forward onto the ledger", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Folio balance forward", "type": "object" }, "closed_at": { "format": "date-time", "title": "Closed at", "type": "string" }, "due_at": { "format": "date-time", "title": "Payment due at", "type": "string" }, "external_invoice_number": { "title": "Operator-facing invoice number", "type": "string" }, "kind": { "enum": [ "guest", "master", "group_master", "company_ar", "house", "comp", "rebate" ], "title": "Folio kind", "type": "string" }, "number": { "title": "Folio number", "type": "string" }, "opened_at": { "format": "date-time", "title": "Opened at", "type": "string" }, "reopened_at": { "format": "date-time", "title": "Reopened at", "type": "string" }, "status": { "enum": [ "open", "closed", "void" ], "title": "Folio status", "type": "string" }, "window_number": { "title": "Window number (1..=8)", "type": "integer" } }, "required": [ "number", "status", "kind", "window_number", "balance", "opened_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.folio:read" ] } ], "summary": "Search Folio", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.folio_routing_rule/objects/{id}": { "get": { "description": "Read an existing instance.\n\nStructured contractual logic for routing charges between folios. Encodes 'route all charges except telephone to the master folio at 50% capped at $500/day' shapes that every group / corporate / negotiated contract expresses. The folio handler walks active rules at charge post-time and applies the matching one — lowest `priority` number wins; ties broken by `effective_from`.", "operationId": "get_hospitality_folio_routing_rule", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio_routing_rule" }, "properties": { "additionalProperties": false, "properties": { "applies_to": { "enum": [ "all", "charge_codes", "charge_categories", "percentage", "capped_amount" ], "title": "Applies to", "type": "string" }, "cap_amount": { "description": "Cap on routed total (applies_to = capped_amount)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Folio routing rule cap amount", "type": "object" }, "charge_category_filter": { "items": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "type": "string" }, "title": "Charge category filter (applies_to = charge_categories)", "type": "array" }, "charge_code_filter": { "items": { "type": "string" }, "title": "Charge code filter (applies_to = charge_codes)", "type": "array" }, "effective_from": { "format": "date", "title": "Effective from", "type": "string" }, "effective_to": { "format": "date", "title": "Effective to", "type": "string" }, "id": { "title": "Rule id", "type": "string" }, "percentage": { "format": "decimal", "title": "Routed fraction (applies_to = percentage)", "type": "string" }, "priority": { "title": "Rule priority (lower evaluates first)", "type": "integer" } }, "required": [ "id", "effective_from", "applies_to", "priority" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.folio_routing_rule:read" ] } ], "summary": "Read Folio routing rule", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.folio_routing_rule/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nStructured contractual logic for routing charges between folios. Encodes 'route all charges except telephone to the master folio at 50% capped at $500/day' shapes that every group / corporate / negotiated contract expresses. The folio handler walks active rules at charge post-time and applies the matching one — lowest `priority` number wins; ties broken by `effective_from`.", "operationId": "get_hospitality_folio_routing_rule_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.folio_routing_rule" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.folio_routing_rule:read" ] } ], "summary": "Read Folio routing rule as of a watermark", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.folio_routing_rule/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nStructured contractual logic for routing charges between folios. Encodes 'route all charges except telephone to the master folio at 50% capped at $500/day' shapes that every group / corporate / negotiated contract expresses. The folio handler walks active rules at charge post-time and applies the matching one — lowest `priority` number wins; ties broken by `effective_from`.", "operationId": "list_links_hospitality_folio_routing_rule", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.folio_routing_rule:read" ] } ], "summary": "List links of Folio routing rule", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.folio_routing_rule_at_property", "hospitality.link.folio_routing_rule_source", "hospitality.link.folio_routing_rule_target" ] } } ] }, "/v1/object-types/hospitality.folio_routing_rule/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nStructured contractual logic for routing charges between folios. Encodes 'route all charges except telephone to the master folio at 50% capped at $500/day' shapes that every group / corporate / negotiated contract expresses. The folio handler walks active rules at charge post-time and applies the matching one — lowest `priority` number wins; ties broken by `effective_from`.", "operationId": "traverse_hospitality_folio_routing_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.folio_routing_rule_at_property", "hospitality.link.folio_routing_rule_source", "hospitality.link.folio_routing_rule_target" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.folio_routing_rule:read" ] } ], "summary": "Traverse from Folio routing rule", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.folio_routing_rule/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nStructured contractual logic for routing charges between folios. Encodes 'route all charges except telephone to the master folio at 50% capped at $500/day' shapes that every group / corporate / negotiated contract expresses. The folio handler walks active rules at charge post-time and applies the matching one — lowest `priority` number wins; ties broken by `effective_from`.", "operationId": "search_hospitality_folio_routing_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applies_to" }, "type": { "const": "eq" }, "value": { "enum": [ "all", "charge_codes", "charge_categories", "percentage", "capped_amount" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "charge_code_filter" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "charge_category_filter" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "percentage" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "percentage" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "percentage" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cap_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "priority" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "priority" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "priority" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "effective_from", "effective_to", "applies_to", "percentage", "priority" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.folio_routing_rule" }, "properties": { "additionalProperties": false, "properties": { "applies_to": { "enum": [ "all", "charge_codes", "charge_categories", "percentage", "capped_amount" ], "title": "Applies to", "type": "string" }, "cap_amount": { "description": "Cap on routed total (applies_to = capped_amount)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Folio routing rule cap amount", "type": "object" }, "charge_category_filter": { "items": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "type": "string" }, "title": "Charge category filter (applies_to = charge_categories)", "type": "array" }, "charge_code_filter": { "items": { "type": "string" }, "title": "Charge code filter (applies_to = charge_codes)", "type": "array" }, "effective_from": { "format": "date", "title": "Effective from", "type": "string" }, "effective_to": { "format": "date", "title": "Effective to", "type": "string" }, "id": { "title": "Rule id", "type": "string" }, "percentage": { "format": "decimal", "title": "Routed fraction (applies_to = percentage)", "type": "string" }, "priority": { "title": "Rule priority (lower evaluates first)", "type": "integer" } }, "required": [ "id", "effective_from", "applies_to", "priority" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.folio_routing_rule:read" ] } ], "summary": "Search Folio routing rule", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.fraud_network_contribution/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA confirmed fraud outcome this house offered to Watchtower, the card rail's federated fraud network (proposal 0029): a dispute lost for fraud (`chargeback_lost_fraud`, the issuer's word) or an assessment applied as a block on the house's own evidence (`confirmed_fraud`, the house's word — at another house it sends a hold to review, never blocks it, and it may not rest on the network's own answer), carried as salted one-way fingerprints of the card, the guest's email and phone. Only the digests reach the network, never the identifiers, never the booking; the network never tells another house which house contributed. Recorded by the card rail only, under the house's `fraud_network` consent; `withdraw_fraud_signal` takes it back out (forward-only — answers already given stand), by the house or, on its review of a contested answer, by the platform on the house's behalf (`withdrawn_by`). One per source (`source_reference`, the processor's dispute id or the assessment id).", "operationId": "get_hospitality_fraud_network_contribution", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fraud_network_contribution" }, "properties": { "additionalProperties": false, "properties": { "contributed_at": { "format": "date-time", "title": "When the outcome was offered", "type": "string" }, "fingerprints": { "title": "The digests offered, as `[{kind, digest}]` — `kind` one of card / email / phone, `digest` 64 lower-case hex (HMAC-SHA256 under the network salt). Never an identifier" }, "id": { "title": "Contribution id", "type": "string" }, "outcome": { "enum": [ "chargeback_lost_fraud", "confirmed_fraud" ], "title": "The confirmed outcome contributed", "type": "string" }, "salt_epoch": { "title": "The network salt generation the digests were taken under", "type": "integer" }, "source_reference": { "title": "What the outcome was read from — the processor's dispute id or the assessment id; one contribution per source", "type": "string" }, "status": { "enum": [ "active", "withdrawn" ], "title": "Whether the contribution stands in the network", "type": "string" }, "withdrawal_reason": { "title": "Why it was taken back, in words", "type": "string" }, "withdrawn_at": { "format": "date-time", "title": "When it was taken back out of the network", "type": "string" }, "withdrawn_by": { "enum": [ "house", "platform" ], "title": "Who took it back — the house, or the platform on its review of a contest, on the house's behalf. Absent on a withdrawal recorded before 2026-11-03, which was the house's", "type": "string" } }, "required": [ "id", "outcome", "status", "salt_epoch", "contributed_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.fraud_network_contribution:read" ] } ], "summary": "Read Fraud network contribution", "tags": [ "fraud_network" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.fraud_network_contribution/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA confirmed fraud outcome this house offered to Watchtower, the card rail's federated fraud network (proposal 0029): a dispute lost for fraud (`chargeback_lost_fraud`, the issuer's word) or an assessment applied as a block on the house's own evidence (`confirmed_fraud`, the house's word — at another house it sends a hold to review, never blocks it, and it may not rest on the network's own answer), carried as salted one-way fingerprints of the card, the guest's email and phone. Only the digests reach the network, never the identifiers, never the booking; the network never tells another house which house contributed. Recorded by the card rail only, under the house's `fraud_network` consent; `withdraw_fraud_signal` takes it back out (forward-only — answers already given stand), by the house or, on its review of a contested answer, by the platform on the house's behalf (`withdrawn_by`). One per source (`source_reference`, the processor's dispute id or the assessment id).", "operationId": "get_hospitality_fraud_network_contribution_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.fraud_network_contribution" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.fraud_network_contribution:read" ] } ], "summary": "Read Fraud network contribution as of a watermark", "tags": [ "fraud_network" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.fraud_network_contribution/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA confirmed fraud outcome this house offered to Watchtower, the card rail's federated fraud network (proposal 0029): a dispute lost for fraud (`chargeback_lost_fraud`, the issuer's word) or an assessment applied as a block on the house's own evidence (`confirmed_fraud`, the house's word — at another house it sends a hold to review, never blocks it, and it may not rest on the network's own answer), carried as salted one-way fingerprints of the card, the guest's email and phone. Only the digests reach the network, never the identifiers, never the booking; the network never tells another house which house contributed. Recorded by the card rail only, under the house's `fraud_network` consent; `withdraw_fraud_signal` takes it back out (forward-only — answers already given stand), by the house or, on its review of a contested answer, by the platform on the house's behalf (`withdrawn_by`). One per source (`source_reference`, the processor's dispute id or the assessment id).", "operationId": "list_links_hospitality_fraud_network_contribution", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.fraud_network_contribution:read" ] } ], "summary": "List links of Fraud network contribution", "tags": [ "fraud_network" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.fraud_network_contribution_at_property", "hospitality.link.fraud_network_contribution_for_assessment", "hospitality.link.fraud_network_contribution_for_payment" ] } } ] }, "/v1/object-types/hospitality.fraud_network_contribution/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA confirmed fraud outcome this house offered to Watchtower, the card rail's federated fraud network (proposal 0029): a dispute lost for fraud (`chargeback_lost_fraud`, the issuer's word) or an assessment applied as a block on the house's own evidence (`confirmed_fraud`, the house's word — at another house it sends a hold to review, never blocks it, and it may not rest on the network's own answer), carried as salted one-way fingerprints of the card, the guest's email and phone. Only the digests reach the network, never the identifiers, never the booking; the network never tells another house which house contributed. Recorded by the card rail only, under the house's `fraud_network` consent; `withdraw_fraud_signal` takes it back out (forward-only — answers already given stand), by the house or, on its review of a contested answer, by the platform on the house's behalf (`withdrawn_by`). One per source (`source_reference`, the processor's dispute id or the assessment id).", "operationId": "traverse_hospitality_fraud_network_contribution", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.fraud_network_contribution_at_property", "hospitality.link.fraud_network_contribution_for_assessment", "hospitality.link.fraud_network_contribution_for_payment" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.fraud_network_contribution:read" ] } ], "summary": "Traverse from Fraud network contribution", "tags": [ "fraud_network" ] } }, "/v1/object-types/hospitality.fraud_network_contribution/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA confirmed fraud outcome this house offered to Watchtower, the card rail's federated fraud network (proposal 0029): a dispute lost for fraud (`chargeback_lost_fraud`, the issuer's word) or an assessment applied as a block on the house's own evidence (`confirmed_fraud`, the house's word — at another house it sends a hold to review, never blocks it, and it may not rest on the network's own answer), carried as salted one-way fingerprints of the card, the guest's email and phone. Only the digests reach the network, never the identifiers, never the booking; the network never tells another house which house contributed. Recorded by the card rail only, under the house's `fraud_network` consent; `withdraw_fraud_signal` takes it back out (forward-only — answers already given stand), by the house or, on its review of a contested answer, by the platform on the house's behalf (`withdrawn_by`). One per source (`source_reference`, the processor's dispute id or the assessment id).", "operationId": "search_hospitality_fraud_network_contribution", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "outcome" }, "type": { "const": "eq" }, "value": { "enum": [ "chargeback_lost_fraud", "confirmed_fraud" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "withdrawn" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fingerprints" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "salt_epoch" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "salt_epoch" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "salt_epoch" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contributed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contributed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contributed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "withdrawn_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "withdrawn_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "withdrawn_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "withdrawal_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "withdrawal_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "withdrawn_by" }, "type": { "const": "eq" }, "value": { "enum": [ "house", "platform" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "outcome", "status", "source_reference", "salt_epoch", "contributed_at", "withdrawn_at", "withdrawal_reason", "withdrawn_by" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fraud_network_contribution" }, "properties": { "additionalProperties": false, "properties": { "contributed_at": { "format": "date-time", "title": "When the outcome was offered", "type": "string" }, "fingerprints": { "title": "The digests offered, as `[{kind, digest}]` — `kind` one of card / email / phone, `digest` 64 lower-case hex (HMAC-SHA256 under the network salt). Never an identifier" }, "id": { "title": "Contribution id", "type": "string" }, "outcome": { "enum": [ "chargeback_lost_fraud", "confirmed_fraud" ], "title": "The confirmed outcome contributed", "type": "string" }, "salt_epoch": { "title": "The network salt generation the digests were taken under", "type": "integer" }, "source_reference": { "title": "What the outcome was read from — the processor's dispute id or the assessment id; one contribution per source", "type": "string" }, "status": { "enum": [ "active", "withdrawn" ], "title": "Whether the contribution stands in the network", "type": "string" }, "withdrawal_reason": { "title": "Why it was taken back, in words", "type": "string" }, "withdrawn_at": { "format": "date-time", "title": "When it was taken back out of the network", "type": "string" }, "withdrawn_by": { "enum": [ "house", "platform" ], "title": "Who took it back — the house, or the platform on its review of a contest, on the house's behalf. Absent on a withdrawal recorded before 2026-11-03, which was the house's", "type": "string" } }, "required": [ "id", "outcome", "status", "salt_epoch", "contributed_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.fraud_network_contribution:read" ] } ], "summary": "Search Fraud network contribution", "tags": [ "fraud_network" ] } }, "/v1/object-types/hospitality.fraud_network_signal/objects/{id}": { "get": { "description": "Read an existing instance.\n\nWhat Watchtower, the card rail's federated fraud network (proposal 0029), answered when this house asked about a card, email or phone before holding a card — frozen as issued; only a contest is ever added. `match_present` says whether a fraud outcome on the rail (contributed within the last two years) carries one of the digests; the count, the breadth of houses behind it and its recency are bucketed, and breadth reads only `below_cohort` until the cohort floor is met — the network never says which house, nor how many. `band_floor` is the lowest risk band the rail lets the hold's assessment carry and `floor_basis` why: a card match blocks only on the house's own loss or on another house's recent issuer-confirmed loss that a second house or the guest's contact corroborates; anything else sends the hold to review. A desk that believes the guest contests the answer (`contest_fraud_network_signal`), which puts it before the platform's review and lets the next answer for the same subject take the hold to review instead (`desk_override`, `override_of`). `fingerprints` keeps the digests the house asked about, so the platform's review of a contest can find the contributions the answer rested on. Recorded by the card rail only.", "operationId": "get_hospitality_fraud_network_signal", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fraud_network_signal" }, "properties": { "additionalProperties": false, "properties": { "band_floor": { "enum": [ "low", "medium", "high", "block", "not_assessed" ], "title": "The lowest band the hold's assessment may carry given this answer", "type": "string" }, "contest_reason": { "title": "Why the desk contested it, in words", "type": "string" }, "contested_at": { "format": "date-time", "title": "When the desk contested this answer for the platform's review", "type": "string" }, "contributor_breadth": { "enum": [ "none", "below_cohort", "cohort_met" ], "title": "Whether the houses behind the match meet the cohort floor", "type": "string" }, "expires_at": { "format": "date-time", "title": "When the answer stops being a fair read (24 hours on)", "type": "string" }, "fingerprints": { "title": "The digests the house asked about, as `[{kind, digest}]` — one per kind queried, 64 lower-case hex under the network salt, never an identifier — kept so the platform's review of a contest can find the contributions behind the answer (since 2026-11-03; an answer frozen before then carries none)" }, "floor_basis": { "enum": [ "none", "contact", "card_unconfirmed", "card_corroborated", "card_own_house", "desk_override" ], "title": "Why the answer set that floor — none, contact, card_unconfirmed, card_corroborated, card_own_house or desk_override", "type": "string" }, "id": { "title": "Signal id", "type": "string" }, "issued_at": { "format": "date-time", "title": "When the network answered", "type": "string" }, "kinds_queried": { "items": { "enum": [ "card", "email", "phone" ], "type": "string" }, "title": "The identifier kinds the house could ask about", "type": "array" }, "match_count_bucket": { "enum": [ "none", "one", "few", "many" ], "title": "How many matching outcomes, bucketed", "type": "string" }, "match_present": { "title": "Whether any confirmed outcome on the network carries one of them", "type": "boolean" }, "matched_kinds": { "items": { "enum": [ "card", "email", "phone" ], "type": "string" }, "title": "Which identifier kinds matched", "type": "array" }, "override_of": { "format": "uuid", "title": "The contested answer this one takes to review instead (desk_override)", "type": "string", "x-aerandil-references": "hospitality.fraud_network_signal" }, "recency_bucket": { "enum": [ "none", "within_30_days", "within_180_days", "older" ], "title": "How recent the newest matching outcome is", "type": "string" }, "salt_epoch": { "title": "The network salt generation the read was taken under", "type": "integer" }, "subject_id": { "title": "The subject's id", "type": "string" }, "subject_kind": { "enum": [ "reservation", "payment", "charge", "person", "loyalty_redemption", "folio" ], "title": "What the risk read was about", "type": "string" } }, "required": [ "id", "subject_kind", "subject_id", "kinds_queried", "match_present", "matched_kinds", "match_count_bucket", "contributor_breadth", "recency_bucket", "band_floor", "salt_epoch", "issued_at", "expires_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.fraud_network_signal:read" ] } ], "summary": "Read Fraud network signal", "tags": [ "fraud_network" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.fraud_network_signal/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nWhat Watchtower, the card rail's federated fraud network (proposal 0029), answered when this house asked about a card, email or phone before holding a card — frozen as issued; only a contest is ever added. `match_present` says whether a fraud outcome on the rail (contributed within the last two years) carries one of the digests; the count, the breadth of houses behind it and its recency are bucketed, and breadth reads only `below_cohort` until the cohort floor is met — the network never says which house, nor how many. `band_floor` is the lowest risk band the rail lets the hold's assessment carry and `floor_basis` why: a card match blocks only on the house's own loss or on another house's recent issuer-confirmed loss that a second house or the guest's contact corroborates; anything else sends the hold to review. A desk that believes the guest contests the answer (`contest_fraud_network_signal`), which puts it before the platform's review and lets the next answer for the same subject take the hold to review instead (`desk_override`, `override_of`). `fingerprints` keeps the digests the house asked about, so the platform's review of a contest can find the contributions the answer rested on. Recorded by the card rail only.", "operationId": "get_hospitality_fraud_network_signal_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.fraud_network_signal" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.fraud_network_signal:read" ] } ], "summary": "Read Fraud network signal as of a watermark", "tags": [ "fraud_network" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.fraud_network_signal/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nWhat Watchtower, the card rail's federated fraud network (proposal 0029), answered when this house asked about a card, email or phone before holding a card — frozen as issued; only a contest is ever added. `match_present` says whether a fraud outcome on the rail (contributed within the last two years) carries one of the digests; the count, the breadth of houses behind it and its recency are bucketed, and breadth reads only `below_cohort` until the cohort floor is met — the network never says which house, nor how many. `band_floor` is the lowest risk band the rail lets the hold's assessment carry and `floor_basis` why: a card match blocks only on the house's own loss or on another house's recent issuer-confirmed loss that a second house or the guest's contact corroborates; anything else sends the hold to review. A desk that believes the guest contests the answer (`contest_fraud_network_signal`), which puts it before the platform's review and lets the next answer for the same subject take the hold to review instead (`desk_override`, `override_of`). `fingerprints` keeps the digests the house asked about, so the platform's review of a contest can find the contributions the answer rested on. Recorded by the card rail only.", "operationId": "list_links_hospitality_fraud_network_signal", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.fraud_network_signal:read" ] } ], "summary": "List links of Fraud network signal", "tags": [ "fraud_network" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.fraud_assessment_consulted_network", "hospitality.link.fraud_network_signal_at_property" ] } } ] }, "/v1/object-types/hospitality.fraud_network_signal/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nWhat Watchtower, the card rail's federated fraud network (proposal 0029), answered when this house asked about a card, email or phone before holding a card — frozen as issued; only a contest is ever added. `match_present` says whether a fraud outcome on the rail (contributed within the last two years) carries one of the digests; the count, the breadth of houses behind it and its recency are bucketed, and breadth reads only `below_cohort` until the cohort floor is met — the network never says which house, nor how many. `band_floor` is the lowest risk band the rail lets the hold's assessment carry and `floor_basis` why: a card match blocks only on the house's own loss or on another house's recent issuer-confirmed loss that a second house or the guest's contact corroborates; anything else sends the hold to review. A desk that believes the guest contests the answer (`contest_fraud_network_signal`), which puts it before the platform's review and lets the next answer for the same subject take the hold to review instead (`desk_override`, `override_of`). `fingerprints` keeps the digests the house asked about, so the platform's review of a contest can find the contributions the answer rested on. Recorded by the card rail only.", "operationId": "traverse_hospitality_fraud_network_signal", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.fraud_assessment_consulted_network", "hospitality.link.fraud_network_signal_at_property" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.fraud_network_signal:read" ] } ], "summary": "Traverse from Fraud network signal", "tags": [ "fraud_network" ] } }, "/v1/object-types/hospitality.fraud_network_signal/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nWhat Watchtower, the card rail's federated fraud network (proposal 0029), answered when this house asked about a card, email or phone before holding a card — frozen as issued; only a contest is ever added. `match_present` says whether a fraud outcome on the rail (contributed within the last two years) carries one of the digests; the count, the breadth of houses behind it and its recency are bucketed, and breadth reads only `below_cohort` until the cohort floor is met — the network never says which house, nor how many. `band_floor` is the lowest risk band the rail lets the hold's assessment carry and `floor_basis` why: a card match blocks only on the house's own loss or on another house's recent issuer-confirmed loss that a second house or the guest's contact corroborates; anything else sends the hold to review. A desk that believes the guest contests the answer (`contest_fraud_network_signal`), which puts it before the platform's review and lets the next answer for the same subject take the hold to review instead (`desk_override`, `override_of`). `fingerprints` keeps the digests the house asked about, so the platform's review of a contest can find the contributions the answer rested on. Recorded by the card rail only.", "operationId": "search_hospitality_fraud_network_signal", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "subject_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "reservation", "payment", "charge", "person", "loyalty_redemption", "folio" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "subject_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "subject_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "subject_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "subject_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kinds_queried" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "card", "email", "phone" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "match_present" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "matched_kinds" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "card", "email", "phone" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "match_count_bucket" }, "type": { "const": "eq" }, "value": { "enum": [ "none", "one", "few", "many" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contributor_breadth" }, "type": { "const": "eq" }, "value": { "enum": [ "none", "below_cohort", "cohort_met" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recency_bucket" }, "type": { "const": "eq" }, "value": { "enum": [ "none", "within_30_days", "within_180_days", "older" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "band_floor" }, "type": { "const": "eq" }, "value": { "enum": [ "low", "medium", "high", "block", "not_assessed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "floor_basis" }, "type": { "const": "eq" }, "value": { "enum": [ "none", "contact", "card_unconfirmed", "card_corroborated", "card_own_house", "desk_override" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "override_of" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.fraud_network_signal" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contested_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contested_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contested_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contest_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contest_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "salt_epoch" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "salt_epoch" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "salt_epoch" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fingerprints" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "subject_kind", "subject_id", "match_count_bucket", "contributor_breadth", "recency_bucket", "band_floor", "floor_basis", "contested_at", "contest_reason", "salt_epoch", "issued_at", "expires_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fraud_network_signal" }, "properties": { "additionalProperties": false, "properties": { "band_floor": { "enum": [ "low", "medium", "high", "block", "not_assessed" ], "title": "The lowest band the hold's assessment may carry given this answer", "type": "string" }, "contest_reason": { "title": "Why the desk contested it, in words", "type": "string" }, "contested_at": { "format": "date-time", "title": "When the desk contested this answer for the platform's review", "type": "string" }, "contributor_breadth": { "enum": [ "none", "below_cohort", "cohort_met" ], "title": "Whether the houses behind the match meet the cohort floor", "type": "string" }, "expires_at": { "format": "date-time", "title": "When the answer stops being a fair read (24 hours on)", "type": "string" }, "fingerprints": { "title": "The digests the house asked about, as `[{kind, digest}]` — one per kind queried, 64 lower-case hex under the network salt, never an identifier — kept so the platform's review of a contest can find the contributions behind the answer (since 2026-11-03; an answer frozen before then carries none)" }, "floor_basis": { "enum": [ "none", "contact", "card_unconfirmed", "card_corroborated", "card_own_house", "desk_override" ], "title": "Why the answer set that floor — none, contact, card_unconfirmed, card_corroborated, card_own_house or desk_override", "type": "string" }, "id": { "title": "Signal id", "type": "string" }, "issued_at": { "format": "date-time", "title": "When the network answered", "type": "string" }, "kinds_queried": { "items": { "enum": [ "card", "email", "phone" ], "type": "string" }, "title": "The identifier kinds the house could ask about", "type": "array" }, "match_count_bucket": { "enum": [ "none", "one", "few", "many" ], "title": "How many matching outcomes, bucketed", "type": "string" }, "match_present": { "title": "Whether any confirmed outcome on the network carries one of them", "type": "boolean" }, "matched_kinds": { "items": { "enum": [ "card", "email", "phone" ], "type": "string" }, "title": "Which identifier kinds matched", "type": "array" }, "override_of": { "format": "uuid", "title": "The contested answer this one takes to review instead (desk_override)", "type": "string", "x-aerandil-references": "hospitality.fraud_network_signal" }, "recency_bucket": { "enum": [ "none", "within_30_days", "within_180_days", "older" ], "title": "How recent the newest matching outcome is", "type": "string" }, "salt_epoch": { "title": "The network salt generation the read was taken under", "type": "integer" }, "subject_id": { "title": "The subject's id", "type": "string" }, "subject_kind": { "enum": [ "reservation", "payment", "charge", "person", "loyalty_redemption", "folio" ], "title": "What the risk read was about", "type": "string" } }, "required": [ "id", "subject_kind", "subject_id", "kinds_queried", "match_present", "matched_kinds", "match_count_bucket", "contributor_breadth", "recency_bucket", "band_floor", "salt_epoch", "issued_at", "expires_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.fraud_network_signal:read" ] } ], "summary": "Search Fraud network signal", "tags": [ "fraud_network" ] } }, "/v1/object-types/hospitality.fraud_risk_assessment/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA typed fraud-risk assessment issued by an agent (or, less commonly, a human risk analyst logging a manual assessment into the audit trail) against a reservation, payment, charge, person, or loyalty redemption. Mostly-immutable post-issue: the score / band / recommended_action / confidence / factors / reason_codes / rationale / risk_context_snapshot are frozen at write time so the audit trail is what the model saw at decision time, not against today's profile. The decision_*, applied_*, escalation_*, and rejection_* fields mutate exactly once on the transition out of `suggested` — gated by the `decision_status_transitions` cross-link validator. Doubly load-bearing for chargeback-dispute defence: card networks accept frozen-feature evidence in dispute response.", "operationId": "get_hospitality_fraud_risk_assessment", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fraud_risk_assessment" }, "properties": { "additionalProperties": false, "properties": { "applied_action_correlation_id": { "title": "correlation_id of the chained action's ApplyActionResponse (set when apply chained into a typed action)", "type": "string" }, "applied_action_kind": { "enum": [ "approve_proceed", "decline_block", "step_up_3ds_initiated", "step_up_kyc_initiated", "decline_with_refund", "decline_with_hold", "approve_with_manual_review" ], "title": "Action class actually taken on `applied` transition", "type": "string" }, "band": { "enum": [ "low", "medium", "high", "block", "not_assessed" ], "title": "Risk band ordinal", "type": "string" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Operator-facing confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Calibrated probability [0, 1] — set when the model emits one", "type": "string" }, "coverage_guaranteed": { "title": "True when the vendor's chargeback-guarantee terms cover this decision (per-decision, not per-vendor)", "type": "boolean" }, "coverage_terms_uri": { "title": "Optional pointer to the vendor's coverage terms applicable to this decision", "type": "string" }, "decided_at": { "format": "date-time", "title": "When the assessment transitioned out of suggested", "type": "string" }, "decided_by": { "title": "`principal.stable_id()` of the deciding principal", "type": "string" }, "decision_status": { "enum": [ "suggested", "applied", "rejected", "escalated", "expired", "superseded" ], "title": "Lifecycle state", "type": "string" }, "escalation_reason": { "enum": [ "low_confidence", "policy_block", "high_value", "chargeback_history_match", "watchlist_hit", "kyc_failure", "three_ds_failure", "manual_review_required", "vendor_uncertainty", "regulatory_review", "operator_override" ], "title": "Reason recorded on escalation", "type": "string" }, "escalation_target_staff_ref": { "format": "uuid", "title": "Optional explicit staff assignment on escalation", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "expires_at": { "format": "date-time", "title": "After this, decision_status moves to expired", "type": "string" }, "factors_considered": { "items": { "enum": [ "payment_signal", "identity_signal", "behavioural_signal", "device_signal", "velocity_signal", "geo_signal", "lead_time", "loyalty_account_age", "prior_chargeback_history", "prior_recovery_history", "third_party_payer_flag", "vcn_detected", "injection_history", "network_outcome", "kyc_outcome", "three_ds_outcome", "watchlist_match", "graph_signal", "fraud_network_signal", "other" ], "type": "string" }, "title": "Signal categories the assessment conditioned on", "type": "array" }, "feature_payload_hash": { "title": "SHA-256 of the canonical JSON of the input features (tamper- evidence anchor for chargeback-dispute defence)", "type": "string" }, "fire_point": { "enum": [ "at_booking", "at_payment", "at_check_in", "at_folio_close", "on_chargeback_attempt" ], "title": "Lifecycle moment the assessment fired at", "type": "string" }, "folio_charge_ref": { "format": "uuid", "title": "Optional charge anchor (set for charge-scoped assessments at `at_payment` / `at_folio_close` fire-points)", "type": "string", "x-aerandil-references": "hospitality.charge" }, "id": { "title": "Assessment id", "type": "string" }, "issued_at": { "format": "date-time", "title": "When the agent emitted the assessment", "type": "string" }, "person_ref": { "format": "uuid", "title": "Optional denormalised person anchor (set when the booking has an identified guest or when the assessment is person-scoped)", "type": "string", "x-aerandil-references": "hospitality.person" }, "policy_outcomes": { "items": { "enum": [ "psd2_sca_required", "psd2_sca_out_of_scope_moto", "psd2_sca_exempted_low_value", "psd2_sca_exempted_trusted_beneficiaries", "psd2_sca_exempted_tra", "psd2_sca_exempted_recurring", "psd2_sca_exempted_corporate_payment", "three_ds_y", "three_ds_a", "three_ds_u", "three_ds_n", "three_ds_r", "three_ds_not_attempted", "gdpr_art22_explanation_required", "pci_token_only", "pci_last4_only", "facta_red_flag_match", "fincen_8300_threshold_met", "eu_ai_act_high_risk_processing", "ccpa_admt_notice_required", "none" ], "type": "string" }, "title": "Compliance flags observed during scoring", "type": "array" }, "rationale_text": { "title": "Human-readable explanation surfaced to operators", "type": "string" }, "reason_codes": { "title": "Explanation array — each entry carries a code, severity, and signed contribution to the final score (JSON; host populates per documented shape)" }, "recommended_action": { "enum": [ "approve", "review", "step_up_3ds", "step_up_kyc", "decline", "escalate" ], "title": "Recommended action class", "type": "string" }, "rejection_reason": { "title": "Free-text reason on reject (gold-standard decision-log pattern)", "type": "string" }, "reservation_ref": { "format": "uuid", "title": "Optional denormalised reservation anchor (set for reservation-scoped assessments)", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "risk_context_snapshot": { "title": "Frozen context snapshot at issue time (§3.1.1; JSON; host populates per recommended shape)" }, "score": { "format": "decimal", "title": "Raw numeric score on the [0, 100] scale", "type": "string" }, "score_calibrated": { "format": "decimal", "title": "Optional calibrated probability [0, 1] when the model emits one", "type": "string" }, "subject_id": { "title": "Id of the typed object the assessment scored (resolved against `subject_kind`)", "type": "string" }, "subject_kind": { "enum": [ "reservation", "payment", "charge", "person", "loyalty_redemption", "folio" ], "title": "What kind of object the assessment scored", "type": "string" }, "superseded_by_assessment_ref": { "format": "uuid", "title": "Newer assessment that replaces this one (set on supersedence)", "type": "string", "x-aerandil-references": "hospitality.fraud_risk_assessment" }, "triggered_rules": { "title": "Custom-rule provenance when the score path went through rules (JSON array of {rule_id, rule_version?, action?})" }, "vendor_id": { "title": "Vendor identity (denormalised from Principal::Agent.vendor)", "type": "string" }, "vendor_model_version": { "title": "Vendor model version when exposed (e.g. stripe_radar_v3)", "type": "string" } }, "required": [ "id", "subject_kind", "subject_id", "fire_point", "vendor_id", "confidence", "factors_considered", "issued_at", "expires_at", "decision_status", "policy_outcomes" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.fraud_risk_assessment:read" ] } ], "summary": "Read Fraud risk assessment", "tags": [ "fraud_detection" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.fraud_risk_assessment/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA typed fraud-risk assessment issued by an agent (or, less commonly, a human risk analyst logging a manual assessment into the audit trail) against a reservation, payment, charge, person, or loyalty redemption. Mostly-immutable post-issue: the score / band / recommended_action / confidence / factors / reason_codes / rationale / risk_context_snapshot are frozen at write time so the audit trail is what the model saw at decision time, not against today's profile. The decision_*, applied_*, escalation_*, and rejection_* fields mutate exactly once on the transition out of `suggested` — gated by the `decision_status_transitions` cross-link validator. Doubly load-bearing for chargeback-dispute defence: card networks accept frozen-feature evidence in dispute response.", "operationId": "get_hospitality_fraud_risk_assessment_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.fraud_risk_assessment" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.fraud_risk_assessment:read" ] } ], "summary": "Read Fraud risk assessment as of a watermark", "tags": [ "fraud_detection" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.fraud_risk_assessment/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA typed fraud-risk assessment issued by an agent (or, less commonly, a human risk analyst logging a manual assessment into the audit trail) against a reservation, payment, charge, person, or loyalty redemption. Mostly-immutable post-issue: the score / band / recommended_action / confidence / factors / reason_codes / rationale / risk_context_snapshot are frozen at write time so the audit trail is what the model saw at decision time, not against today's profile. The decision_*, applied_*, escalation_*, and rejection_* fields mutate exactly once on the transition out of `suggested` — gated by the `decision_status_transitions` cross-link validator. Doubly load-bearing for chargeback-dispute defence: card networks accept frozen-feature evidence in dispute response.", "operationId": "list_links_hospitality_fraud_risk_assessment", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.fraud_risk_assessment:read" ] } ], "summary": "List links of Fraud risk assessment", "tags": [ "fraud_detection" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.fraud_assessment_at_property", "hospitality.link.fraud_assessment_chained_action_target", "hospitality.link.fraud_assessment_consulted_network", "hospitality.link.fraud_assessment_escalated_to_staff_member", "hospitality.link.fraud_assessment_for_charge", "hospitality.link.fraud_assessment_for_person", "hospitality.link.fraud_assessment_for_prior_triage", "hospitality.link.fraud_assessment_for_reservation", "hospitality.link.fraud_assessment_references_external_record", "hospitality.link.fraud_assessment_superseded_by", "hospitality.link.fraud_network_contribution_for_assessment", "hospitality.link.payment_for_fraud_assessment", "hospitality.link.workflow_run_targets_fraud_risk_assessment" ] } } ] }, "/v1/object-types/hospitality.fraud_risk_assessment/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA typed fraud-risk assessment issued by an agent (or, less commonly, a human risk analyst logging a manual assessment into the audit trail) against a reservation, payment, charge, person, or loyalty redemption. Mostly-immutable post-issue: the score / band / recommended_action / confidence / factors / reason_codes / rationale / risk_context_snapshot are frozen at write time so the audit trail is what the model saw at decision time, not against today's profile. The decision_*, applied_*, escalation_*, and rejection_* fields mutate exactly once on the transition out of `suggested` — gated by the `decision_status_transitions` cross-link validator. Doubly load-bearing for chargeback-dispute defence: card networks accept frozen-feature evidence in dispute response.", "operationId": "traverse_hospitality_fraud_risk_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.fraud_assessment_at_property", "hospitality.link.fraud_assessment_chained_action_target", "hospitality.link.fraud_assessment_consulted_network", "hospitality.link.fraud_assessment_escalated_to_staff_member", "hospitality.link.fraud_assessment_for_charge", "hospitality.link.fraud_assessment_for_person", "hospitality.link.fraud_assessment_for_prior_triage", "hospitality.link.fraud_assessment_for_reservation", "hospitality.link.fraud_assessment_references_external_record", "hospitality.link.fraud_assessment_superseded_by", "hospitality.link.fraud_network_contribution_for_assessment", "hospitality.link.payment_for_fraud_assessment", "hospitality.link.workflow_run_targets_fraud_risk_assessment" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.fraud_risk_assessment:read" ] } ], "summary": "Traverse from Fraud risk assessment", "tags": [ "fraud_detection" ] } }, "/v1/object-types/hospitality.fraud_risk_assessment/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA typed fraud-risk assessment issued by an agent (or, less commonly, a human risk analyst logging a manual assessment into the audit trail) against a reservation, payment, charge, person, or loyalty redemption. Mostly-immutable post-issue: the score / band / recommended_action / confidence / factors / reason_codes / rationale / risk_context_snapshot are frozen at write time so the audit trail is what the model saw at decision time, not against today's profile. The decision_*, applied_*, escalation_*, and rejection_* fields mutate exactly once on the transition out of `suggested` — gated by the `decision_status_transitions` cross-link validator. Doubly load-bearing for chargeback-dispute defence: card networks accept frozen-feature evidence in dispute response.", "operationId": "search_hospitality_fraud_risk_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "subject_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "reservation", "payment", "charge", "person", "loyalty_redemption", "folio" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "subject_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "subject_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "subject_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "subject_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reservation_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "person_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.person" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "folio_charge_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.charge" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fire_point" }, "type": { "const": "eq" }, "value": { "enum": [ "at_booking", "at_payment", "at_check_in", "at_folio_close", "on_chargeback_attempt" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor_model_version" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor_model_version" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor_model_version" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor_model_version" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "score" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "score" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "score" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "score_calibrated" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "score_calibrated" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "score_calibrated" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "band" }, "type": { "const": "eq" }, "value": { "enum": [ "low", "medium", "high", "block", "not_assessed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_action" }, "type": { "const": "eq" }, "value": { "enum": [ "approve", "review", "step_up_3ds", "step_up_kyc", "decline", "escalate" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confidence" }, "type": { "const": "eq" }, "value": { "enum": [ "low", "medium", "high" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confidence_score" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confidence_score" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confidence_score" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "factors_considered" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "payment_signal", "identity_signal", "behavioural_signal", "device_signal", "velocity_signal", "geo_signal", "lead_time", "loyalty_account_age", "prior_chargeback_history", "prior_recovery_history", "third_party_payer_flag", "vcn_detected", "injection_history", "network_outcome", "kyc_outcome", "three_ds_outcome", "watchlist_match", "graph_signal", "fraud_network_signal", "other" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reason_codes" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "triggered_rules" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rationale_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rationale_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "risk_context_snapshot" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decision_status" }, "type": { "const": "eq" }, "value": { "enum": [ "suggested", "applied", "rejected", "escalated", "expired", "superseded" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_action_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "approve_proceed", "decline_block", "step_up_3ds_initiated", "step_up_kyc_initiated", "decline_with_refund", "decline_with_hold", "approve_with_manual_review" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_action_correlation_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_action_correlation_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_action_correlation_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_action_correlation_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "escalation_reason" }, "type": { "const": "eq" }, "value": { "enum": [ "low_confidence", "policy_block", "high_value", "chargeback_history_match", "watchlist_hit", "kyc_failure", "three_ds_failure", "manual_review_required", "vendor_uncertainty", "regulatory_review", "operator_override" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "escalation_target_staff_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejection_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejection_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "superseded_by_assessment_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.fraud_risk_assessment" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "policy_outcomes" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "psd2_sca_required", "psd2_sca_out_of_scope_moto", "psd2_sca_exempted_low_value", "psd2_sca_exempted_trusted_beneficiaries", "psd2_sca_exempted_tra", "psd2_sca_exempted_recurring", "psd2_sca_exempted_corporate_payment", "three_ds_y", "three_ds_a", "three_ds_u", "three_ds_n", "three_ds_r", "three_ds_not_attempted", "gdpr_art22_explanation_required", "pci_token_only", "pci_last4_only", "facta_red_flag_match", "fincen_8300_threshold_met", "eu_ai_act_high_risk_processing", "ccpa_admt_notice_required", "none" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "coverage_guaranteed" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "coverage_terms_uri" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "coverage_terms_uri" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "coverage_terms_uri" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "coverage_terms_uri" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "feature_payload_hash" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "feature_payload_hash" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "feature_payload_hash" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "feature_payload_hash" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "subject_kind", "subject_id", "fire_point", "vendor_id", "vendor_model_version", "score", "score_calibrated", "band", "recommended_action", "confidence", "confidence_score", "rationale_text", "issued_at", "expires_at", "decision_status", "decided_at", "decided_by", "applied_action_kind", "applied_action_correlation_id", "escalation_reason", "rejection_reason", "coverage_terms_uri", "feature_payload_hash" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.fraud_risk_assessment" }, "properties": { "additionalProperties": false, "properties": { "applied_action_correlation_id": { "title": "correlation_id of the chained action's ApplyActionResponse (set when apply chained into a typed action)", "type": "string" }, "applied_action_kind": { "enum": [ "approve_proceed", "decline_block", "step_up_3ds_initiated", "step_up_kyc_initiated", "decline_with_refund", "decline_with_hold", "approve_with_manual_review" ], "title": "Action class actually taken on `applied` transition", "type": "string" }, "band": { "enum": [ "low", "medium", "high", "block", "not_assessed" ], "title": "Risk band ordinal", "type": "string" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Operator-facing confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Calibrated probability [0, 1] — set when the model emits one", "type": "string" }, "coverage_guaranteed": { "title": "True when the vendor's chargeback-guarantee terms cover this decision (per-decision, not per-vendor)", "type": "boolean" }, "coverage_terms_uri": { "title": "Optional pointer to the vendor's coverage terms applicable to this decision", "type": "string" }, "decided_at": { "format": "date-time", "title": "When the assessment transitioned out of suggested", "type": "string" }, "decided_by": { "title": "`principal.stable_id()` of the deciding principal", "type": "string" }, "decision_status": { "enum": [ "suggested", "applied", "rejected", "escalated", "expired", "superseded" ], "title": "Lifecycle state", "type": "string" }, "escalation_reason": { "enum": [ "low_confidence", "policy_block", "high_value", "chargeback_history_match", "watchlist_hit", "kyc_failure", "three_ds_failure", "manual_review_required", "vendor_uncertainty", "regulatory_review", "operator_override" ], "title": "Reason recorded on escalation", "type": "string" }, "escalation_target_staff_ref": { "format": "uuid", "title": "Optional explicit staff assignment on escalation", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "expires_at": { "format": "date-time", "title": "After this, decision_status moves to expired", "type": "string" }, "factors_considered": { "items": { "enum": [ "payment_signal", "identity_signal", "behavioural_signal", "device_signal", "velocity_signal", "geo_signal", "lead_time", "loyalty_account_age", "prior_chargeback_history", "prior_recovery_history", "third_party_payer_flag", "vcn_detected", "injection_history", "network_outcome", "kyc_outcome", "three_ds_outcome", "watchlist_match", "graph_signal", "fraud_network_signal", "other" ], "type": "string" }, "title": "Signal categories the assessment conditioned on", "type": "array" }, "feature_payload_hash": { "title": "SHA-256 of the canonical JSON of the input features (tamper- evidence anchor for chargeback-dispute defence)", "type": "string" }, "fire_point": { "enum": [ "at_booking", "at_payment", "at_check_in", "at_folio_close", "on_chargeback_attempt" ], "title": "Lifecycle moment the assessment fired at", "type": "string" }, "folio_charge_ref": { "format": "uuid", "title": "Optional charge anchor (set for charge-scoped assessments at `at_payment` / `at_folio_close` fire-points)", "type": "string", "x-aerandil-references": "hospitality.charge" }, "id": { "title": "Assessment id", "type": "string" }, "issued_at": { "format": "date-time", "title": "When the agent emitted the assessment", "type": "string" }, "person_ref": { "format": "uuid", "title": "Optional denormalised person anchor (set when the booking has an identified guest or when the assessment is person-scoped)", "type": "string", "x-aerandil-references": "hospitality.person" }, "policy_outcomes": { "items": { "enum": [ "psd2_sca_required", "psd2_sca_out_of_scope_moto", "psd2_sca_exempted_low_value", "psd2_sca_exempted_trusted_beneficiaries", "psd2_sca_exempted_tra", "psd2_sca_exempted_recurring", "psd2_sca_exempted_corporate_payment", "three_ds_y", "three_ds_a", "three_ds_u", "three_ds_n", "three_ds_r", "three_ds_not_attempted", "gdpr_art22_explanation_required", "pci_token_only", "pci_last4_only", "facta_red_flag_match", "fincen_8300_threshold_met", "eu_ai_act_high_risk_processing", "ccpa_admt_notice_required", "none" ], "type": "string" }, "title": "Compliance flags observed during scoring", "type": "array" }, "rationale_text": { "title": "Human-readable explanation surfaced to operators", "type": "string" }, "reason_codes": { "title": "Explanation array — each entry carries a code, severity, and signed contribution to the final score (JSON; host populates per documented shape)" }, "recommended_action": { "enum": [ "approve", "review", "step_up_3ds", "step_up_kyc", "decline", "escalate" ], "title": "Recommended action class", "type": "string" }, "rejection_reason": { "title": "Free-text reason on reject (gold-standard decision-log pattern)", "type": "string" }, "reservation_ref": { "format": "uuid", "title": "Optional denormalised reservation anchor (set for reservation-scoped assessments)", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "risk_context_snapshot": { "title": "Frozen context snapshot at issue time (§3.1.1; JSON; host populates per recommended shape)" }, "score": { "format": "decimal", "title": "Raw numeric score on the [0, 100] scale", "type": "string" }, "score_calibrated": { "format": "decimal", "title": "Optional calibrated probability [0, 1] when the model emits one", "type": "string" }, "subject_id": { "title": "Id of the typed object the assessment scored (resolved against `subject_kind`)", "type": "string" }, "subject_kind": { "enum": [ "reservation", "payment", "charge", "person", "loyalty_redemption", "folio" ], "title": "What kind of object the assessment scored", "type": "string" }, "superseded_by_assessment_ref": { "format": "uuid", "title": "Newer assessment that replaces this one (set on supersedence)", "type": "string", "x-aerandil-references": "hospitality.fraud_risk_assessment" }, "triggered_rules": { "title": "Custom-rule provenance when the score path went through rules (JSON array of {rule_id, rule_version?, action?})" }, "vendor_id": { "title": "Vendor identity (denormalised from Principal::Agent.vendor)", "type": "string" }, "vendor_model_version": { "title": "Vendor model version when exposed (e.g. stripe_radar_v3)", "type": "string" } }, "required": [ "id", "subject_kind", "subject_id", "fire_point", "vendor_id", "confidence", "factors_considered", "issued_at", "expires_at", "decision_status", "policy_outcomes" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.fraud_risk_assessment:read" ] } ], "summary": "Search Fraud risk assessment", "tags": [ "fraud_detection" ] } }, "/v1/object-types/hospitality.function_event/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne booked use of a function space — a meeting, a reception, a dinner — on a date, in a window, in a setup style, with the expected / guaranteed / set / actual attendance. `tentative` holds the diary and commits nothing; `definite` is contracted; `actual` is recorded after the function with the attendance the banquet charges bill on; `cancelled` is terminal. The events of a group hang off its block through `function_event_for_block`.", "operationId": "get_hospitality_function_event", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_event" }, "properties": { "additionalProperties": false, "properties": { "actual_count": { "title": "Actual attendance, recorded after the function", "type": "integer" }, "do_not_move": { "title": "The client was promised this room; reschedule refuses a space change", "type": "boolean" }, "end_at": { "format": "date-time", "title": "Doors close", "type": "string" }, "event_date": { "format": "date", "title": "The property-local day the event is on", "type": "string" }, "event_type": { "enum": [ "meeting", "conference", "breakout", "reception", "breakfast", "lunch", "dinner", "banquet", "wedding_ceremony", "wedding_breakfast", "exhibition", "rehearsal", "other" ], "title": "What kind of function", "type": "string" }, "expected_count": { "title": "Expected attendance (the forecast number)", "type": "integer" }, "guarantee_due_at": { "format": "date-time", "title": "When the guarantee is due; after it the number may only rise", "type": "string" }, "guaranteed_count": { "title": "Guaranteed attendance — the contracted minimum the client bills on", "type": "integer" }, "id": { "title": "Event id", "type": "string" }, "name": { "title": "Event name", "type": "string" }, "notes": { "title": "Notes for the operating departments", "type": "string" }, "rental": { "description": "Function space rental agreed for the event", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Function event rental", "type": "object" }, "set_count": { "title": "How many the room was set for", "type": "integer" }, "setup_from": { "format": "date-time", "title": "When the setup crew may have the room (before start_at)", "type": "string" }, "setup_style": { "enum": [ "theatre", "classroom", "boardroom", "u_shape", "hollow_square", "banquet_rounds", "cabaret", "reception", "exhibition", "existing" ], "title": "How the room is set", "type": "string" }, "start_at": { "format": "date-time", "title": "Doors open", "type": "string" }, "status": { "enum": [ "tentative", "definite", "actual", "cancelled" ], "title": "Event status", "type": "string" }, "teardown_until": { "format": "date-time", "title": "When the room must be clear again (after end_at)", "type": "string" } }, "required": [ "id", "name", "event_type", "status", "event_date", "start_at", "end_at", "setup_style", "expected_count", "do_not_move" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.function_event:read" ] } ], "summary": "Read Function event", "tags": [ "catering" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.function_event/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne booked use of a function space — a meeting, a reception, a dinner — on a date, in a window, in a setup style, with the expected / guaranteed / set / actual attendance. `tentative` holds the diary and commits nothing; `definite` is contracted; `actual` is recorded after the function with the attendance the banquet charges bill on; `cancelled` is terminal. The events of a group hang off its block through `function_event_for_block`.", "operationId": "get_hospitality_function_event_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.function_event" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.function_event:read" ] } ], "summary": "Read Function event as of a watermark", "tags": [ "catering" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.function_event/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne booked use of a function space — a meeting, a reception, a dinner — on a date, in a window, in a setup style, with the expected / guaranteed / set / actual attendance. `tentative` holds the diary and commits nothing; `definite` is contracted; `actual` is recorded after the function with the attendance the banquet charges bill on; `cancelled` is terminal. The events of a group hang off its block through `function_event_for_block`.", "operationId": "list_links_hospitality_function_event", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.function_event:read" ] } ], "summary": "List links of Function event", "tags": [ "catering" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.function_event_at_property", "hospitality.link.function_event_contact", "hospitality.link.function_event_for_block", "hospitality.link.function_event_has_order", "hospitality.link.function_event_in_space" ] } } ] }, "/v1/object-types/hospitality.function_event/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne booked use of a function space — a meeting, a reception, a dinner — on a date, in a window, in a setup style, with the expected / guaranteed / set / actual attendance. `tentative` holds the diary and commits nothing; `definite` is contracted; `actual` is recorded after the function with the attendance the banquet charges bill on; `cancelled` is terminal. The events of a group hang off its block through `function_event_for_block`.", "operationId": "traverse_hospitality_function_event", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.function_event_at_property", "hospitality.link.function_event_contact", "hospitality.link.function_event_for_block", "hospitality.link.function_event_has_order", "hospitality.link.function_event_in_space" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.function_event:read" ] } ], "summary": "Traverse from Function event", "tags": [ "catering" ] } }, "/v1/object-types/hospitality.function_event/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne booked use of a function space — a meeting, a reception, a dinner — on a date, in a window, in a setup style, with the expected / guaranteed / set / actual attendance. `tentative` holds the diary and commits nothing; `definite` is contracted; `actual` is recorded after the function with the attendance the banquet charges bill on; `cancelled` is terminal. The events of a group hang off its block through `function_event_for_block`.", "operationId": "search_hospitality_function_event", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "event_type" }, "type": { "const": "eq" }, "value": { "enum": [ "meeting", "conference", "breakout", "reception", "breakfast", "lunch", "dinner", "banquet", "wedding_ceremony", "wedding_breakfast", "exhibition", "rehearsal", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "tentative", "definite", "actual", "cancelled" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "event_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "event_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "event_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "start_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "start_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "start_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "end_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "end_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "end_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "setup_from" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "setup_from" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "setup_from" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "teardown_until" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "teardown_until" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "teardown_until" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "setup_style" }, "type": { "const": "eq" }, "value": { "enum": [ "theatre", "classroom", "boardroom", "u_shape", "hollow_square", "banquet_rounds", "cabaret", "reception", "exhibition", "existing" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expected_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expected_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expected_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "guaranteed_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "guaranteed_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "guaranteed_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "guarantee_due_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "guarantee_due_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "guarantee_due_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "set_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "set_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "set_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "actual_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "actual_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "actual_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rental" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "do_not_move" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "name", "event_type", "status", "event_date", "start_at", "end_at", "setup_from", "teardown_until", "setup_style", "expected_count", "guaranteed_count", "guarantee_due_at", "set_count", "actual_count", "notes" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_event" }, "properties": { "additionalProperties": false, "properties": { "actual_count": { "title": "Actual attendance, recorded after the function", "type": "integer" }, "do_not_move": { "title": "The client was promised this room; reschedule refuses a space change", "type": "boolean" }, "end_at": { "format": "date-time", "title": "Doors close", "type": "string" }, "event_date": { "format": "date", "title": "The property-local day the event is on", "type": "string" }, "event_type": { "enum": [ "meeting", "conference", "breakout", "reception", "breakfast", "lunch", "dinner", "banquet", "wedding_ceremony", "wedding_breakfast", "exhibition", "rehearsal", "other" ], "title": "What kind of function", "type": "string" }, "expected_count": { "title": "Expected attendance (the forecast number)", "type": "integer" }, "guarantee_due_at": { "format": "date-time", "title": "When the guarantee is due; after it the number may only rise", "type": "string" }, "guaranteed_count": { "title": "Guaranteed attendance — the contracted minimum the client bills on", "type": "integer" }, "id": { "title": "Event id", "type": "string" }, "name": { "title": "Event name", "type": "string" }, "notes": { "title": "Notes for the operating departments", "type": "string" }, "rental": { "description": "Function space rental agreed for the event", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Function event rental", "type": "object" }, "set_count": { "title": "How many the room was set for", "type": "integer" }, "setup_from": { "format": "date-time", "title": "When the setup crew may have the room (before start_at)", "type": "string" }, "setup_style": { "enum": [ "theatre", "classroom", "boardroom", "u_shape", "hollow_square", "banquet_rounds", "cabaret", "reception", "exhibition", "existing" ], "title": "How the room is set", "type": "string" }, "start_at": { "format": "date-time", "title": "Doors open", "type": "string" }, "status": { "enum": [ "tentative", "definite", "actual", "cancelled" ], "title": "Event status", "type": "string" }, "teardown_until": { "format": "date-time", "title": "When the room must be clear again (after end_at)", "type": "string" } }, "required": [ "id", "name", "event_type", "status", "event_date", "start_at", "end_at", "setup_style", "expected_count", "do_not_move" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.function_event:read" ] } ], "summary": "Search Function event", "tags": [ "catering" ] } }, "/v1/object-types/hospitality.function_space/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA bookable function room at a property — what the house sells by the hour. `capacities` declares how many the room holds per setup style, and a booking is checked against the style it asks for. A divisible room is one space with sections linked through `function_space_section_of`: an event in the combined room occupies every section, and a booked section blocks the whole.", "operationId": "get_hospitality_function_space", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_space" }, "properties": { "additionalProperties": false, "properties": { "area_sqm": { "format": "decimal", "title": "Floor area in square metres", "type": "string" }, "capacities": { "description": "Capacity per setup style", "items": { "properties": { "capacity": { "type": "integer" }, "setup_style": { "enum": [ "theatre", "classroom", "boardroom", "u_shape", "hollow_square", "banquet_rounds", "cabaret", "reception", "exhibition", "existing" ], "type": "string" } }, "required": [ "setup_style", "capacity" ], "type": "object" }, "title": "Function space capacities", "type": "array" }, "code": { "title": "Operator-facing code", "type": "string" }, "divisible": { "title": "Whether the room splits into sections", "type": "boolean" }, "id": { "title": "Function space id", "type": "string" }, "location": { "title": "Where in the house (floor, wing)", "type": "string" }, "name": { "title": "Display name", "type": "string" }, "notes": { "title": "Operational notes (access, power, ceiling height)", "type": "string" }, "status": { "enum": [ "active", "out_of_service", "retired" ], "title": "Space status", "type": "string" } }, "required": [ "id", "code", "name", "status", "capacities", "divisible" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.function_space:read" ] } ], "summary": "Read Function space", "tags": [ "catering" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.function_space/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA bookable function room at a property — what the house sells by the hour. `capacities` declares how many the room holds per setup style, and a booking is checked against the style it asks for. A divisible room is one space with sections linked through `function_space_section_of`: an event in the combined room occupies every section, and a booked section blocks the whole.", "operationId": "get_hospitality_function_space_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.function_space" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.function_space:read" ] } ], "summary": "Read Function space as of a watermark", "tags": [ "catering" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.function_space/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA bookable function room at a property — what the house sells by the hour. `capacities` declares how many the room holds per setup style, and a booking is checked against the style it asks for. A divisible room is one space with sections linked through `function_space_section_of`: an event in the combined room occupies every section, and a booked section blocks the whole.", "operationId": "list_links_hospitality_function_space", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.function_space:read" ] } ], "summary": "List links of Function space", "tags": [ "catering" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.function_event_in_space", "hospitality.link.function_space_at_property", "hospitality.link.function_space_section_of" ] } } ] }, "/v1/object-types/hospitality.function_space/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA bookable function room at a property — what the house sells by the hour. `capacities` declares how many the room holds per setup style, and a booking is checked against the style it asks for. A divisible room is one space with sections linked through `function_space_section_of`: an event in the combined room occupies every section, and a booked section blocks the whole.", "operationId": "traverse_hospitality_function_space", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.function_event_in_space", "hospitality.link.function_space_at_property", "hospitality.link.function_space_section_of" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.function_space:read" ] } ], "summary": "Traverse from Function space", "tags": [ "catering" ] } }, "/v1/object-types/hospitality.function_space/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA bookable function room at a property — what the house sells by the hour. `capacities` declares how many the room holds per setup style, and a booking is checked against the style it asks for. A divisible room is one space with sections linked through `function_space_section_of`: an event in the combined room occupies every section, and a booked section blocks the whole.", "operationId": "search_hospitality_function_space", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "out_of_service", "retired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "capacities" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "capacity": { "type": "integer" }, "setup_style": { "enum": [ "theatre", "classroom", "boardroom", "u_shape", "hollow_square", "banquet_rounds", "cabaret", "reception", "exhibition", "existing" ], "type": "string" } }, "required": [ "setup_style", "capacity" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "divisible" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "area_sqm" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "area_sqm" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "area_sqm" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "location" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "location" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "location" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "location" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "code", "name", "status", "area_sqm", "location", "notes" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.function_space" }, "properties": { "additionalProperties": false, "properties": { "area_sqm": { "format": "decimal", "title": "Floor area in square metres", "type": "string" }, "capacities": { "description": "Capacity per setup style", "items": { "properties": { "capacity": { "type": "integer" }, "setup_style": { "enum": [ "theatre", "classroom", "boardroom", "u_shape", "hollow_square", "banquet_rounds", "cabaret", "reception", "exhibition", "existing" ], "type": "string" } }, "required": [ "setup_style", "capacity" ], "type": "object" }, "title": "Function space capacities", "type": "array" }, "code": { "title": "Operator-facing code", "type": "string" }, "divisible": { "title": "Whether the room splits into sections", "type": "boolean" }, "id": { "title": "Function space id", "type": "string" }, "location": { "title": "Where in the house (floor, wing)", "type": "string" }, "name": { "title": "Display name", "type": "string" }, "notes": { "title": "Operational notes (access, power, ceiling height)", "type": "string" }, "status": { "enum": [ "active", "out_of_service", "retired" ], "title": "Space status", "type": "string" } }, "required": [ "id", "code", "name", "status", "capacities", "divisible" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.function_space:read" ] } ], "summary": "Search Function space", "tags": [ "catering" ] } }, "/v1/object-types/hospitality.grounding_scope/objects/{id}": { "get": { "description": "Read an existing instance.\n\nAn admin-curated grounding bundle for agents (design D11): a named subset of object types and metrics, synonym/sample-value hints, curation instructions, and a repository of verified invocations — human-blessed NL→action/metric/function examples with `verified_by`/`verified_at` provenance (the Snowflake verified-query pattern). Agent definitions reference one via `grounding_scope_ref`; the retrieval-context lane injects it deterministically, and answers can cite which verified example grounded them. Referential validity of `target_ref` against the registry is enforced by the consuming lane at read time, not frozen at write time — the registry evolves under the scope.", "operationId": "get_hospitality_grounding_scope", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.grounding_scope" }, "properties": { "additionalProperties": false, "properties": { "defined_at": { "format": "date-time", "title": "When the scope was defined", "type": "string" }, "defined_by": { "title": "`principal.stable_id()` of the curator", "type": "string" }, "id": { "title": "Scope id", "type": "string" }, "instructions": { "title": "Curator instructions injected into the retrieval context", "type": "string" }, "metric_refs": { "items": { "type": "string" }, "title": "MetricDef names in scope", "type": "array" }, "object_type_refs": { "items": { "type": "string" }, "title": "Object-type api-names in scope", "type": "array" }, "scope_key": { "title": "Stable key agent definitions reference", "type": "string" }, "scope_status": { "enum": [ "active", "retired" ], "title": "Curation lifecycle", "type": "string" }, "synonyms": { "title": "Term→canonical hints + sample values (JSON; curator-owned shape)" }, "title": { "title": "Display name", "type": "string" }, "verified_invocations": { "description": "Human-blessed NL→invocation examples with provenance", "items": { "properties": { "params_example": {}, "target_kind": { "enum": [ "action", "metric", "function" ], "type": "string" }, "target_ref": { "type": "string" }, "utterance": { "type": "string" }, "verified_at": { "format": "date-time", "type": "string" }, "verified_by": { "type": "string" } }, "required": [ "utterance", "target_kind", "target_ref", "verified_by", "verified_at" ], "type": "object" }, "title": "Grounding scope verified invocations", "type": "array" } }, "required": [ "id", "scope_key", "title", "object_type_refs", "metric_refs", "verified_invocations", "scope_status", "defined_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.grounding_scope:read" ] } ], "summary": "Read Grounding scope", "tags": [ "agents" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.grounding_scope/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nAn admin-curated grounding bundle for agents (design D11): a named subset of object types and metrics, synonym/sample-value hints, curation instructions, and a repository of verified invocations — human-blessed NL→action/metric/function examples with `verified_by`/`verified_at` provenance (the Snowflake verified-query pattern). Agent definitions reference one via `grounding_scope_ref`; the retrieval-context lane injects it deterministically, and answers can cite which verified example grounded them. Referential validity of `target_ref` against the registry is enforced by the consuming lane at read time, not frozen at write time — the registry evolves under the scope.", "operationId": "get_hospitality_grounding_scope_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.grounding_scope" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.grounding_scope:read" ] } ], "summary": "Read Grounding scope as of a watermark", "tags": [ "agents" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.grounding_scope/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nAn admin-curated grounding bundle for agents (design D11): a named subset of object types and metrics, synonym/sample-value hints, curation instructions, and a repository of verified invocations — human-blessed NL→action/metric/function examples with `verified_by`/`verified_at` provenance (the Snowflake verified-query pattern). Agent definitions reference one via `grounding_scope_ref`; the retrieval-context lane injects it deterministically, and answers can cite which verified example grounded them. Referential validity of `target_ref` against the registry is enforced by the consuming lane at read time, not frozen at write time — the registry evolves under the scope.", "operationId": "search_hospitality_grounding_scope", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "scope_key" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "scope_key" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "scope_key" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "scope_key" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "title" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "title" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "title" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "title" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "instructions" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "instructions" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "object_type_refs" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "metric_refs" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "synonyms" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "verified_invocations" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "params_example": {}, "target_kind": { "enum": [ "action", "metric", "function" ], "type": "string" }, "target_ref": { "type": "string" }, "utterance": { "type": "string" }, "verified_at": { "format": "date-time", "type": "string" }, "verified_by": { "type": "string" } }, "required": [ "utterance", "target_kind", "target_ref", "verified_by", "verified_at" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "scope_status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "retired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "defined_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "defined_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "defined_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "defined_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "defined_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "defined_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "defined_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "scope_key", "title", "instructions", "scope_status", "defined_by", "defined_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.grounding_scope" }, "properties": { "additionalProperties": false, "properties": { "defined_at": { "format": "date-time", "title": "When the scope was defined", "type": "string" }, "defined_by": { "title": "`principal.stable_id()` of the curator", "type": "string" }, "id": { "title": "Scope id", "type": "string" }, "instructions": { "title": "Curator instructions injected into the retrieval context", "type": "string" }, "metric_refs": { "items": { "type": "string" }, "title": "MetricDef names in scope", "type": "array" }, "object_type_refs": { "items": { "type": "string" }, "title": "Object-type api-names in scope", "type": "array" }, "scope_key": { "title": "Stable key agent definitions reference", "type": "string" }, "scope_status": { "enum": [ "active", "retired" ], "title": "Curation lifecycle", "type": "string" }, "synonyms": { "title": "Term→canonical hints + sample values (JSON; curator-owned shape)" }, "title": { "title": "Display name", "type": "string" }, "verified_invocations": { "description": "Human-blessed NL→invocation examples with provenance", "items": { "properties": { "params_example": {}, "target_kind": { "enum": [ "action", "metric", "function" ], "type": "string" }, "target_ref": { "type": "string" }, "utterance": { "type": "string" }, "verified_at": { "format": "date-time", "type": "string" }, "verified_by": { "type": "string" } }, "required": [ "utterance", "target_kind", "target_ref", "verified_by", "verified_at" ], "type": "object" }, "title": "Grounding scope verified invocations", "type": "array" } }, "required": [ "id", "scope_key", "title", "object_type_refs", "metric_refs", "verified_invocations", "scope_status", "defined_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.grounding_scope:read" ] } ], "summary": "Search Grounding scope", "tags": [ "agents" ] } }, "/v1/object-types/hospitality.group_block/objects/{id}": { "get": { "description": "Read an existing instance.\n\nAn operational room-block allotment at one property. `status` decides whether the block holds inventory: a `definite` block's unpicked remainder is carried in `availability_day.blocked` and suppresses transient sale, while `tentative` holds nothing. Pickup moves a room from the block's hold to `sold` — net zero against the booking ceiling — and the cutoff fields decide when rooms nobody took go back to the house.", "operationId": "get_hospitality_group_block", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_block" }, "properties": { "additionalProperties": false, "properties": { "cancel_returns_to": { "enum": [ "house", "block" ], "title": "Where a cancelled pickup's room goes", "type": "string" }, "code": { "title": "Operator-facing block code", "type": "string" }, "cutoff_date": { "format": "date", "title": "Cutoff date (mode = fixed)", "type": "string" }, "cutoff_days": { "title": "Days before each stay night to release it (mode = rolling)", "type": "integer" }, "cutoff_mode": { "enum": [ "none", "fixed", "rolling" ], "title": "Cutoff mode", "type": "string" }, "end_date": { "format": "date", "title": "Departure date (exclusive of the last stay night)", "type": "string" }, "id": { "title": "Group block id", "type": "string" }, "name": { "title": "Block name", "type": "string" }, "rate_plan_id": { "format": "uuid", "title": "Block-private rate plan", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "rooming_list_due": { "format": "date", "title": "Date the group owes its rooming list", "type": "string" }, "start_date": { "format": "date", "title": "First stay night", "type": "string" }, "status": { "enum": [ "tentative", "definite", "cancelled" ], "title": "Block status", "type": "string" } }, "required": [ "id", "name", "status", "start_date", "end_date", "cutoff_mode", "cancel_returns_to" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.group_block:read" ] } ], "summary": "Read Group block", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.group_block/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nAn operational room-block allotment at one property. `status` decides whether the block holds inventory: a `definite` block's unpicked remainder is carried in `availability_day.blocked` and suppresses transient sale, while `tentative` holds nothing. Pickup moves a room from the block's hold to `sold` — net zero against the booking ceiling — and the cutoff fields decide when rooms nobody took go back to the house.", "operationId": "get_hospitality_group_block_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.group_block" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.group_block:read" ] } ], "summary": "Read Group block as of a watermark", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.group_block/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nAn operational room-block allotment at one property. `status` decides whether the block holds inventory: a `definite` block's unpicked remainder is carried in `availability_day.blocked` and suppresses transient sale, while `tentative` holds nothing. Pickup moves a room from the block's hold to `sold` — net zero against the booking ceiling — and the cutoff fields decide when rooms nobody took go back to the house.", "operationId": "list_links_hospitality_group_block", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.group_block:read" ] } ], "summary": "List links of Group block", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.block_allocation_of_block", "hospitality.link.block_for_property", "hospitality.link.block_has_master_folio", "hospitality.link.function_event_for_block", "hospitality.link.group_request_has_block", "hospitality.link.reservation_picked_up_from_block" ] } } ] }, "/v1/object-types/hospitality.group_block/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nAn operational room-block allotment at one property. `status` decides whether the block holds inventory: a `definite` block's unpicked remainder is carried in `availability_day.blocked` and suppresses transient sale, while `tentative` holds nothing. Pickup moves a room from the block's hold to `sold` — net zero against the booking ceiling — and the cutoff fields decide when rooms nobody took go back to the house.", "operationId": "traverse_hospitality_group_block", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.block_allocation_of_block", "hospitality.link.block_for_property", "hospitality.link.block_has_master_folio", "hospitality.link.function_event_for_block", "hospitality.link.group_request_has_block", "hospitality.link.reservation_picked_up_from_block" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.group_block:read" ] } ], "summary": "Traverse from Group block", "tags": [ "revenue" ] } }, "/v1/object-types/hospitality.group_block/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nAn operational room-block allotment at one property. `status` decides whether the block holds inventory: a `definite` block's unpicked remainder is carried in `availability_day.blocked` and suppresses transient sale, while `tentative` holds nothing. Pickup moves a room from the block's hold to `sold` — net zero against the booking ceiling — and the cutoff fields decide when rooms nobody took go back to the house.", "operationId": "search_hospitality_group_block", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "tentative", "definite", "cancelled" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "start_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "start_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "start_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "end_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "end_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "end_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cutoff_mode" }, "type": { "const": "eq" }, "value": { "enum": [ "none", "fixed", "rolling" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cutoff_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cutoff_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cutoff_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cutoff_days" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cutoff_days" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cutoff_days" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancel_returns_to" }, "type": { "const": "eq" }, "value": { "enum": [ "house", "block" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rate_plan_id" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.rate_plan" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rooming_list_due" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rooming_list_due" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rooming_list_due" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "name", "code", "status", "start_date", "end_date", "cutoff_mode", "cutoff_date", "cutoff_days", "cancel_returns_to", "rooming_list_due" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_block" }, "properties": { "additionalProperties": false, "properties": { "cancel_returns_to": { "enum": [ "house", "block" ], "title": "Where a cancelled pickup's room goes", "type": "string" }, "code": { "title": "Operator-facing block code", "type": "string" }, "cutoff_date": { "format": "date", "title": "Cutoff date (mode = fixed)", "type": "string" }, "cutoff_days": { "title": "Days before each stay night to release it (mode = rolling)", "type": "integer" }, "cutoff_mode": { "enum": [ "none", "fixed", "rolling" ], "title": "Cutoff mode", "type": "string" }, "end_date": { "format": "date", "title": "Departure date (exclusive of the last stay night)", "type": "string" }, "id": { "title": "Group block id", "type": "string" }, "name": { "title": "Block name", "type": "string" }, "rate_plan_id": { "format": "uuid", "title": "Block-private rate plan", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "rooming_list_due": { "format": "date", "title": "Date the group owes its rooming list", "type": "string" }, "start_date": { "format": "date", "title": "First stay night", "type": "string" }, "status": { "enum": [ "tentative", "definite", "cancelled" ], "title": "Block status", "type": "string" } }, "required": [ "id", "name", "status", "start_date", "end_date", "cutoff_mode", "cancel_returns_to" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.group_block:read" ] } ], "summary": "Search Group block", "tags": [ "revenue" ] } }, "/v1/object-types/hospitality.group_displacement_analysis/objects/{id}": { "get": { "description": "Read an existing instance.\n\nFrozen decision artefact recording the displacement analysis for a group block — Cornell SHA / Sheryl Kimes methodology, carried as audit-grade evidence of the rate floor and decision at the moment they were made. The embedded `forecast_snapshot` pins the transient-room / ADR / occupancy projection at decision time; recomputing against today's forecast undermines the audit trail. Mutation post-write is disallowed by convention — re-decisions create new analyses, not mutations.", "operationId": "get_hospitality_group_displacement_analysis", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_displacement_analysis" }, "properties": { "additionalProperties": false, "properties": { "counter_rate": { "description": "Counter offer ADR (set when decision = counter)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Group displacement analysis counter rate", "type": "object" }, "decided_at": { "format": "date-time", "title": "When the decision was recorded", "type": "string" }, "decided_by": { "title": "Decider principal identifier (matches Principal::stable_id)", "type": "string" }, "decision": { "enum": [ "accept", "decline", "counter" ], "title": "Decision recorded at the moment of analysis", "type": "string" }, "decision_notes": { "title": "Decision notes", "type": "string" }, "displaced_contribution": { "description": "Forfeited transient contribution", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Group displacement analysis displaced contribution", "type": "object" }, "displaced_room_nights": { "title": "Displaced transient room nights", "type": "integer" }, "forecast_snapshot": { "description": "Forecast at decision time", "properties": { "compset_revpar_by_night": { "items": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "type": "array" }, "occupancy_by_night": { "items": { "format": "decimal", "type": "string" }, "type": "array" }, "transient_adr_by_night": { "items": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "type": "array" }, "transient_rooms_by_night": { "items": { "type": "integer" }, "type": "array" } }, "required": [ "transient_rooms_by_night", "transient_adr_by_night" ], "title": "Group displacement analysis forecast snapshot", "type": "object" }, "group_total_revenue": { "description": "Group total revenue (rooms + ancillary)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Group displacement analysis group total revenue", "type": "object" }, "group_variable_cost": { "description": "Group variable cost", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Group displacement analysis group variable cost", "type": "object" }, "id": { "title": "Analysis id", "type": "string" }, "minimum_acceptable_rate": { "description": "Minimum acceptable group ADR (rate floor)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Group displacement analysis minimum acceptable rate", "type": "object" }, "variable_cost_per_room": { "description": "Variable cost per room", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Group displacement analysis variable cost per room", "type": "object" } }, "required": [ "id", "displaced_room_nights", "decision", "decided_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.group_displacement_analysis:read" ] } ], "summary": "Read Group displacement analysis", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.group_displacement_analysis/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nFrozen decision artefact recording the displacement analysis for a group block — Cornell SHA / Sheryl Kimes methodology, carried as audit-grade evidence of the rate floor and decision at the moment they were made. The embedded `forecast_snapshot` pins the transient-room / ADR / occupancy projection at decision time; recomputing against today's forecast undermines the audit trail. Mutation post-write is disallowed by convention — re-decisions create new analyses, not mutations.", "operationId": "get_hospitality_group_displacement_analysis_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.group_displacement_analysis" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.group_displacement_analysis:read" ] } ], "summary": "Read Group displacement analysis as of a watermark", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.group_displacement_analysis/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nFrozen decision artefact recording the displacement analysis for a group block — Cornell SHA / Sheryl Kimes methodology, carried as audit-grade evidence of the rate floor and decision at the moment they were made. The embedded `forecast_snapshot` pins the transient-room / ADR / occupancy projection at decision time; recomputing against today's forecast undermines the audit trail. Mutation post-write is disallowed by convention — re-decisions create new analyses, not mutations.", "operationId": "list_links_hospitality_group_displacement_analysis", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.group_displacement_analysis:read" ] } ], "summary": "List links of Group displacement analysis", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.displacement_analysis_for_request" ] } } ] }, "/v1/object-types/hospitality.group_displacement_analysis/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nFrozen decision artefact recording the displacement analysis for a group block — Cornell SHA / Sheryl Kimes methodology, carried as audit-grade evidence of the rate floor and decision at the moment they were made. The embedded `forecast_snapshot` pins the transient-room / ADR / occupancy projection at decision time; recomputing against today's forecast undermines the audit trail. Mutation post-write is disallowed by convention — re-decisions create new analyses, not mutations.", "operationId": "traverse_hospitality_group_displacement_analysis", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.displacement_analysis_for_request" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.group_displacement_analysis:read" ] } ], "summary": "Traverse from Group displacement analysis", "tags": [ "revenue" ] } }, "/v1/object-types/hospitality.group_displacement_analysis/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nFrozen decision artefact recording the displacement analysis for a group block — Cornell SHA / Sheryl Kimes methodology, carried as audit-grade evidence of the rate floor and decision at the moment they were made. The embedded `forecast_snapshot` pins the transient-room / ADR / occupancy projection at decision time; recomputing against today's forecast undermines the audit trail. Mutation post-write is disallowed by convention — re-decisions create new analyses, not mutations.", "operationId": "search_hospitality_group_displacement_analysis", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "forecast_snapshot" }, "type": { "const": "eq" }, "value": { "properties": { "compset_revpar_by_night": { "items": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "type": "array" }, "occupancy_by_night": { "items": { "format": "decimal", "type": "string" }, "type": "array" }, "transient_adr_by_night": { "items": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "type": "array" }, "transient_rooms_by_night": { "items": { "type": "integer" }, "type": "array" } }, "required": [ "transient_rooms_by_night", "transient_adr_by_night" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "variable_cost_per_room" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "displaced_room_nights" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "displaced_room_nights" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "displaced_room_nights" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "displaced_contribution" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "group_total_revenue" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "group_variable_cost" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "minimum_acceptable_rate" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decision" }, "type": { "const": "eq" }, "value": { "enum": [ "accept", "decline", "counter" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "counter_rate" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decision_notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decision_notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "displaced_room_nights", "decision", "decided_at", "decided_by", "decision_notes" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_displacement_analysis" }, "properties": { "additionalProperties": false, "properties": { "counter_rate": { "description": "Counter offer ADR (set when decision = counter)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Group displacement analysis counter rate", "type": "object" }, "decided_at": { "format": "date-time", "title": "When the decision was recorded", "type": "string" }, "decided_by": { "title": "Decider principal identifier (matches Principal::stable_id)", "type": "string" }, "decision": { "enum": [ "accept", "decline", "counter" ], "title": "Decision recorded at the moment of analysis", "type": "string" }, "decision_notes": { "title": "Decision notes", "type": "string" }, "displaced_contribution": { "description": "Forfeited transient contribution", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Group displacement analysis displaced contribution", "type": "object" }, "displaced_room_nights": { "title": "Displaced transient room nights", "type": "integer" }, "forecast_snapshot": { "description": "Forecast at decision time", "properties": { "compset_revpar_by_night": { "items": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "type": "array" }, "occupancy_by_night": { "items": { "format": "decimal", "type": "string" }, "type": "array" }, "transient_adr_by_night": { "items": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "type": "array" }, "transient_rooms_by_night": { "items": { "type": "integer" }, "type": "array" } }, "required": [ "transient_rooms_by_night", "transient_adr_by_night" ], "title": "Group displacement analysis forecast snapshot", "type": "object" }, "group_total_revenue": { "description": "Group total revenue (rooms + ancillary)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Group displacement analysis group total revenue", "type": "object" }, "group_variable_cost": { "description": "Group variable cost", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Group displacement analysis group variable cost", "type": "object" }, "id": { "title": "Analysis id", "type": "string" }, "minimum_acceptable_rate": { "description": "Minimum acceptable group ADR (rate floor)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Group displacement analysis minimum acceptable rate", "type": "object" }, "variable_cost_per_room": { "description": "Variable cost per room", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Group displacement analysis variable cost per room", "type": "object" } }, "required": [ "id", "displaced_room_nights", "decision", "decided_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.group_displacement_analysis:read" ] } ], "summary": "Search Group displacement analysis", "tags": [ "revenue" ] } }, "/v1/object-types/hospitality.group_request/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe inquiry stage for a group block — corporate booking, wedding, conference, sports team. Carries estimated F&B / spa / other ancillary revenue so displacement analysis can run against realistic assumptions, not just room nights. Multi-property blocks (a wedding booking rooms across two properties) hang off the same group_request via the M:N `group_request_for_property` link.", "operationId": "get_hospitality_group_request", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_request" }, "properties": { "additionalProperties": false, "properties": { "description": { "title": "Notes", "type": "string" }, "estimated_fb_revenue": { "description": "Estimated F&B revenue", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Group request estimated fb revenue", "type": "object" }, "estimated_other_revenue": { "description": "Estimated other ancillary revenue", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Group request estimated other revenue", "type": "object" }, "estimated_spa_revenue": { "description": "Estimated spa revenue", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Group request estimated spa revenue", "type": "object" }, "group_kind": { "enum": [ "corporate", "wedding", "conference", "social", "government", "sports", "tour", "other" ], "title": "Group kind", "type": "string" }, "group_size": { "title": "Estimated attendees", "type": "integer" }, "id": { "title": "Group request id", "type": "string" }, "inquired_at": { "format": "date-time", "title": "When the inquiry was received", "type": "string" }, "requested_arrival": { "format": "date", "title": "Requested arrival", "type": "string" }, "requested_departure": { "format": "date", "title": "Requested departure", "type": "string" }, "room_block_size": { "title": "Room block size", "type": "integer" }, "status": { "enum": [ "inquiry", "tentative", "confirmed", "lost", "cancelled" ], "title": "Funnel status", "type": "string" } }, "required": [ "id", "group_size", "group_kind", "requested_arrival", "requested_departure", "room_block_size", "status", "inquired_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.group_request:read" ] } ], "summary": "Read Group request", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.group_request/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe inquiry stage for a group block — corporate booking, wedding, conference, sports team. Carries estimated F&B / spa / other ancillary revenue so displacement analysis can run against realistic assumptions, not just room nights. Multi-property blocks (a wedding booking rooms across two properties) hang off the same group_request via the M:N `group_request_for_property` link.", "operationId": "get_hospitality_group_request_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.group_request" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.group_request:read" ] } ], "summary": "Read Group request as of a watermark", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.group_request/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe inquiry stage for a group block — corporate booking, wedding, conference, sports team. Carries estimated F&B / spa / other ancillary revenue so displacement analysis can run against realistic assumptions, not just room nights. Multi-property blocks (a wedding booking rooms across two properties) hang off the same group_request via the M:N `group_request_for_property` link.", "operationId": "list_links_hospitality_group_request", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.group_request:read" ] } ], "summary": "List links of Group request", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.displacement_analysis_for_request", "hospitality.link.group_request_converts_to_reservation", "hospitality.link.group_request_for_property", "hospitality.link.group_request_has_block" ] } } ] }, "/v1/object-types/hospitality.group_request/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe inquiry stage for a group block — corporate booking, wedding, conference, sports team. Carries estimated F&B / spa / other ancillary revenue so displacement analysis can run against realistic assumptions, not just room nights. Multi-property blocks (a wedding booking rooms across two properties) hang off the same group_request via the M:N `group_request_for_property` link.", "operationId": "traverse_hospitality_group_request", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.displacement_analysis_for_request", "hospitality.link.group_request_converts_to_reservation", "hospitality.link.group_request_for_property", "hospitality.link.group_request_has_block" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.group_request:read" ] } ], "summary": "Traverse from Group request", "tags": [ "revenue" ] } }, "/v1/object-types/hospitality.group_request/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe inquiry stage for a group block — corporate booking, wedding, conference, sports team. Carries estimated F&B / spa / other ancillary revenue so displacement analysis can run against realistic assumptions, not just room nights. Multi-property blocks (a wedding booking rooms across two properties) hang off the same group_request via the M:N `group_request_for_property` link.", "operationId": "search_hospitality_group_request", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "group_size" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "group_size" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "group_size" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "group_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "corporate", "wedding", "conference", "social", "government", "sports", "tour", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_arrival" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_arrival" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_arrival" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_departure" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_departure" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_departure" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "room_block_size" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "room_block_size" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "room_block_size" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "estimated_fb_revenue" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "estimated_spa_revenue" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "estimated_other_revenue" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "inquiry", "tentative", "confirmed", "lost", "cancelled" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "inquired_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "inquired_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "inquired_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "group_size", "group_kind", "requested_arrival", "requested_departure", "room_block_size", "status", "inquired_at", "description" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.group_request" }, "properties": { "additionalProperties": false, "properties": { "description": { "title": "Notes", "type": "string" }, "estimated_fb_revenue": { "description": "Estimated F&B revenue", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Group request estimated fb revenue", "type": "object" }, "estimated_other_revenue": { "description": "Estimated other ancillary revenue", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Group request estimated other revenue", "type": "object" }, "estimated_spa_revenue": { "description": "Estimated spa revenue", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Group request estimated spa revenue", "type": "object" }, "group_kind": { "enum": [ "corporate", "wedding", "conference", "social", "government", "sports", "tour", "other" ], "title": "Group kind", "type": "string" }, "group_size": { "title": "Estimated attendees", "type": "integer" }, "id": { "title": "Group request id", "type": "string" }, "inquired_at": { "format": "date-time", "title": "When the inquiry was received", "type": "string" }, "requested_arrival": { "format": "date", "title": "Requested arrival", "type": "string" }, "requested_departure": { "format": "date", "title": "Requested departure", "type": "string" }, "room_block_size": { "title": "Room block size", "type": "integer" }, "status": { "enum": [ "inquiry", "tentative", "confirmed", "lost", "cancelled" ], "title": "Funnel status", "type": "string" } }, "required": [ "id", "group_size", "group_kind", "requested_arrival", "requested_departure", "room_block_size", "status", "inquired_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.group_request:read" ] } ], "summary": "Search Group request", "tags": [ "revenue" ] } }, "/v1/object-types/hospitality.guest_check/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe order/check entity: opened against a service table (or takeaway / room service) in a meal period on a business date, owned by a server, open until its payments (check_payment) cover what is due — the payment that brings `balance_due` to zero settles it and marks the table dirty (Simphony model). Carries its running totals, kept by every action that moves them: `subtotal` (live lines, modifier lines included, voided and comped out), `tax_total`, `total_due` (subtotal plus add-on tax), `paid_total` (tips excluded), `tip_total` and `balance_due`. Mutates only through the fnb actions.", "operationId": "get_hospitality_guest_check", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" }, "properties": { "additionalProperties": false, "properties": { "balance_due": { "description": "total_due less paid_total — the payment that brings it to zero settles the check", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Guest check balance due", "type": "object" }, "business_date": { "description": "The hotel date at open (the date the property has open, else its local calendar day) — what every line's price and VAT resolve on, however late in the service it rings. Revenue still reports under the business day of the settle or the folio posting, as the ledger dates it.", "format": "date", "title": "Business date the check belongs to", "type": "string" }, "cleared_at": { "format": "date-time", "title": "When the tray or trolley was collected", "type": "string" }, "conveyance": { "enum": [ "tray", "trolley" ], "title": "Tray or trolley", "type": "string" }, "covers": { "title": "Covers seated", "type": "integer" }, "daypart": { "description": "The meal period the check was opened in — the daypart an `item_price` row may be narrowed to (the bar's lunch price) and a package's meal allowance is matched on. Stamped from the outlet's `meal_periods` when a live check names none. Absent = opened outside the outlet's periods, or before it had any, which only matches rows with no daypart.", "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "title": "Meal period the check rings in", "type": "string" }, "delivered_at": { "format": "date-time", "title": "When the order reached the room", "type": "string" }, "delivery_status": { "description": "taken → dispatched → delivered → cleared, each step only from the one before (`dispatch_room_service`, `deliver_room_service`, `collect_tray`). Independent of the check's own open / settled: a tray is collected after the bill is signed.", "enum": [ "taken", "dispatched", "delivered", "cleared" ], "title": "Where the in-room order is on its dispatch sheet", "type": "string" }, "dispatched_at": { "format": "date-time", "title": "When the order left the kitchen", "type": "string" }, "external_ref": { "title": "Source-system key for replayed / connector-landed checks", "type": "string" }, "number": { "title": "Check number", "type": "string" }, "opened_at": { "format": "date-time", "title": "When the check opened", "type": "string" }, "opened_by": { "title": "Principal::stable_id() of the opening principal", "type": "string" }, "order_kind": { "enum": [ "dine_in", "takeaway", "room_service", "delivery" ], "title": "How the order reaches the guest", "type": "string" }, "paid_total": { "description": "What the check's payments applied to it, tips excluded", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Guest check paid total", "type": "object" }, "promised_at": { "description": "The time quoted to the guest: what `open_check` was given, else twenty minutes after opening for a breakfast order and thirty for any other. The board marks an order late once it passes undelivered.", "format": "date-time", "title": "When the order was promised at the room", "type": "string" }, "room": { "description": "The stay's room number when a check opened for an in-house stay (always, for room service), snapshotted for the runner and the board; the stay itself is the `check_for_stay` link.", "title": "Room number of the stay the check is for", "type": "string" }, "runner_id": { "format": "uuid", "title": "Who ran the order up", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "server_id": { "format": "uuid", "title": "Owning server", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "settled_at": { "format": "date-time", "title": "When the check settled", "type": "string" }, "status": { "enum": [ "open", "settled" ], "title": "Check lifecycle status", "type": "string" }, "subtotal": { "description": "Gross of the live lines (modifier lines included; voided and comped out)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Guest check subtotal", "type": "object" }, "tax_total": { "description": "Tax on the live lines, inclusive and add-on", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Guest check tax total", "type": "object" }, "tip_total": { "description": "Tips taken with the check's payments (a pass-through, not revenue)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Guest check tip total", "type": "object" }, "total_due": { "description": "What the guest owes: subtotal plus add-on (non-inclusive) tax", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Guest check total due", "type": "object" } }, "required": [ "number", "status", "order_kind", "opened_at", "opened_by" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_check:read" ] } ], "summary": "Read Guest check", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.guest_check/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe order/check entity: opened against a service table (or takeaway / room service) in a meal period on a business date, owned by a server, open until its payments (check_payment) cover what is due — the payment that brings `balance_due` to zero settles it and marks the table dirty (Simphony model). Carries its running totals, kept by every action that moves them: `subtotal` (live lines, modifier lines included, voided and comped out), `tax_total`, `total_due` (subtotal plus add-on tax), `paid_total` (tips excluded), `tip_total` and `balance_due`. Mutates only through the fnb actions.", "operationId": "get_hospitality_guest_check_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.guest_check" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_check:read" ] } ], "summary": "Read Guest check as of a watermark", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.guest_check/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe order/check entity: opened against a service table (or takeaway / room service) in a meal period on a business date, owned by a server, open until its payments (check_payment) cover what is due — the payment that brings `balance_due` to zero settles it and marks the table dirty (Simphony model). Carries its running totals, kept by every action that moves them: `subtotal` (live lines, modifier lines included, voided and comped out), `tax_total`, `total_due` (subtotal plus add-on tax), `paid_total` (tips excluded), `tip_total` and `balance_due`. Mutates only through the fnb actions.", "operationId": "list_links_hospitality_guest_check", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_check:read" ] } ], "summary": "List links of Guest check", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.check_at_outlet", "hospitality.link.check_for_stay", "hospitality.link.check_line_on_check", "hospitality.link.check_opened_at_table", "hospitality.link.check_payment_on_check", "hospitality.link.check_settled_to_folio", "hospitality.link.receipt_for_check", "hospitality.link.ticket_for_check" ] } } ] }, "/v1/object-types/hospitality.guest_check/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe order/check entity: opened against a service table (or takeaway / room service) in a meal period on a business date, owned by a server, open until its payments (check_payment) cover what is due — the payment that brings `balance_due` to zero settles it and marks the table dirty (Simphony model). Carries its running totals, kept by every action that moves them: `subtotal` (live lines, modifier lines included, voided and comped out), `tax_total`, `total_due` (subtotal plus add-on tax), `paid_total` (tips excluded), `tip_total` and `balance_due`. Mutates only through the fnb actions.", "operationId": "traverse_hospitality_guest_check", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.check_at_outlet", "hospitality.link.check_for_stay", "hospitality.link.check_line_on_check", "hospitality.link.check_opened_at_table", "hospitality.link.check_payment_on_check", "hospitality.link.check_settled_to_folio", "hospitality.link.receipt_for_check", "hospitality.link.ticket_for_check" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_check:read" ] } ], "summary": "Traverse from Guest check", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.guest_check/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe order/check entity: opened against a service table (or takeaway / room service) in a meal period on a business date, owned by a server, open until its payments (check_payment) cover what is due — the payment that brings `balance_due` to zero settles it and marks the table dirty (Simphony model). Carries its running totals, kept by every action that moves them: `subtotal` (live lines, modifier lines included, voided and comped out), `tax_total`, `total_due` (subtotal plus add-on tax), `paid_total` (tips excluded), `tip_total` and `balance_due`. Mutates only through the fnb actions.", "operationId": "search_hospitality_guest_check", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "number" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "number" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "number" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "number" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "open", "settled" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "order_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "dine_in", "takeaway", "room_service", "delivery" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "daypart" }, "type": { "const": "eq" }, "value": { "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "covers" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "covers" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "covers" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "server_id" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "settled_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "settled_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "settled_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "subtotal" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_total" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "total_due" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "paid_total" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tip_total" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "balance_due" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "room" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "room" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "room" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "room" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "promised_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "promised_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "promised_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delivery_status" }, "type": { "const": "eq" }, "value": { "enum": [ "taken", "dispatched", "delivered", "cleared" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispatched_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispatched_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispatched_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delivered_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delivered_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delivered_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cleared_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cleared_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cleared_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "runner_id" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "conveyance" }, "type": { "const": "eq" }, "value": { "enum": [ "tray", "trolley" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "number", "status", "order_kind", "daypart", "business_date", "covers", "opened_at", "opened_by", "settled_at", "room", "promised_at", "delivery_status", "dispatched_at", "delivered_at", "cleared_at", "conveyance", "external_ref" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_check" }, "properties": { "additionalProperties": false, "properties": { "balance_due": { "description": "total_due less paid_total — the payment that brings it to zero settles the check", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Guest check balance due", "type": "object" }, "business_date": { "description": "The hotel date at open (the date the property has open, else its local calendar day) — what every line's price and VAT resolve on, however late in the service it rings. Revenue still reports under the business day of the settle or the folio posting, as the ledger dates it.", "format": "date", "title": "Business date the check belongs to", "type": "string" }, "cleared_at": { "format": "date-time", "title": "When the tray or trolley was collected", "type": "string" }, "conveyance": { "enum": [ "tray", "trolley" ], "title": "Tray or trolley", "type": "string" }, "covers": { "title": "Covers seated", "type": "integer" }, "daypart": { "description": "The meal period the check was opened in — the daypart an `item_price` row may be narrowed to (the bar's lunch price) and a package's meal allowance is matched on. Stamped from the outlet's `meal_periods` when a live check names none. Absent = opened outside the outlet's periods, or before it had any, which only matches rows with no daypart.", "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "title": "Meal period the check rings in", "type": "string" }, "delivered_at": { "format": "date-time", "title": "When the order reached the room", "type": "string" }, "delivery_status": { "description": "taken → dispatched → delivered → cleared, each step only from the one before (`dispatch_room_service`, `deliver_room_service`, `collect_tray`). Independent of the check's own open / settled: a tray is collected after the bill is signed.", "enum": [ "taken", "dispatched", "delivered", "cleared" ], "title": "Where the in-room order is on its dispatch sheet", "type": "string" }, "dispatched_at": { "format": "date-time", "title": "When the order left the kitchen", "type": "string" }, "external_ref": { "title": "Source-system key for replayed / connector-landed checks", "type": "string" }, "number": { "title": "Check number", "type": "string" }, "opened_at": { "format": "date-time", "title": "When the check opened", "type": "string" }, "opened_by": { "title": "Principal::stable_id() of the opening principal", "type": "string" }, "order_kind": { "enum": [ "dine_in", "takeaway", "room_service", "delivery" ], "title": "How the order reaches the guest", "type": "string" }, "paid_total": { "description": "What the check's payments applied to it, tips excluded", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Guest check paid total", "type": "object" }, "promised_at": { "description": "The time quoted to the guest: what `open_check` was given, else twenty minutes after opening for a breakfast order and thirty for any other. The board marks an order late once it passes undelivered.", "format": "date-time", "title": "When the order was promised at the room", "type": "string" }, "room": { "description": "The stay's room number when a check opened for an in-house stay (always, for room service), snapshotted for the runner and the board; the stay itself is the `check_for_stay` link.", "title": "Room number of the stay the check is for", "type": "string" }, "runner_id": { "format": "uuid", "title": "Who ran the order up", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "server_id": { "format": "uuid", "title": "Owning server", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "settled_at": { "format": "date-time", "title": "When the check settled", "type": "string" }, "status": { "enum": [ "open", "settled" ], "title": "Check lifecycle status", "type": "string" }, "subtotal": { "description": "Gross of the live lines (modifier lines included; voided and comped out)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Guest check subtotal", "type": "object" }, "tax_total": { "description": "Tax on the live lines, inclusive and add-on", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Guest check tax total", "type": "object" }, "tip_total": { "description": "Tips taken with the check's payments (a pass-through, not revenue)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Guest check tip total", "type": "object" }, "total_due": { "description": "What the guest owes: subtotal plus add-on (non-inclusive) tax", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Guest check total due", "type": "object" } }, "required": [ "number", "status", "order_kind", "opened_at", "opened_by" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_check:read" ] } ], "summary": "Search Guest check", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.guest_conversation/objects/{id}": { "get": { "description": "Read an existing instance.\n\nPer-guest cross-channel conversation container. Two-level model per the 2026 vendor convergence: this object is the per-guest anchor; per-reservation segmentation is the optional `anchor_reservation_ref` plus the temporal `guest_conversation_anchored_to_reservation` link. Channel lives on `guest_message`, not here. Lifecycle `state` tracks the outermost outcome so operator UIs route on it; opt-out scope is the in-thread TCPA / WhatsApp / GDPR signal accumulator that the outbound-action validators honour.", "operationId": "get_hospitality_guest_conversation", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_conversation" }, "properties": { "additionalProperties": false, "properties": { "anchor_reservation_ref": { "format": "uuid", "title": "Optional reservation anchor (pre-arrival / in-house / departing)", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "escalation_count": { "title": "Count of triages that escalated (denormalised; §B.1)", "type": "integer" }, "id": { "title": "Conversation id", "type": "string" }, "inbound_count": { "title": "Count of inbound messages (denormalised; §B.1)", "type": "integer" }, "language": { "title": "BCP-47 tag of the guest's most recently detected reply language", "type": "string" }, "last_message_at": { "format": "date-time", "title": "Most recent message timestamp (denormalised, §B.1)", "type": "string" }, "last_message_at_computed_at": { "format": "date-time", "title": "Refresh-discipline pair for `last_message_at`", "type": "string" }, "message_count": { "title": "Count of messages in this conversation (denormalised; §B.1)", "type": "integer" }, "message_count_computed_at": { "format": "date-time", "title": "Refresh pair for the four counters (§B.1 discipline)", "type": "string" }, "opened_at": { "format": "date-time", "title": "When the conversation opened (first message timestamp)", "type": "string" }, "opt_out_scope": { "items": { "enum": [ "sms_marketing", "sms_all", "whatsapp_marketing", "email_marketing", "voice_all", "gdpr_erasure_requested" ], "type": "string" }, "title": "Opt-out signals received in-thread (TCPA / WhatsApp / GDPR)", "type": "array" }, "person_ref": { "format": "uuid", "title": "The guest (person) this conversation belongs to", "type": "string", "x-aerandil-references": "hospitality.person" }, "redactions_applied": { "items": { "enum": [ "pan", "cvv", "government_id", "health_disclosure", "child_safeguarding", "other_pii" ], "type": "string" }, "title": "Aggregated redaction-kind set across the conversation", "type": "array" }, "sentiment_trajectory": { "items": { "format": "decimal", "type": "string" }, "title": "Rolling sentiment scores [-1.0, 1.0] per message (bounded length)", "type": "array" }, "state": { "enum": [ "open", "awaiting_guest", "awaiting_staff", "closed_resolved", "closed_unresolved", "escalated" ], "title": "Lifecycle state", "type": "string" }, "state_reason": { "title": "Optional short reason on terminal state transitions", "type": "string" }, "triage_count": { "title": "Count of triages issued in this conversation (denormalised; §B.1)", "type": "integer" } }, "required": [ "id", "opened_at", "last_message_at", "state", "opt_out_scope", "redactions_applied" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_conversation:read" ] } ], "summary": "Read Guest conversation", "tags": [ "messaging" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.guest_conversation/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nPer-guest cross-channel conversation container. Two-level model per the 2026 vendor convergence: this object is the per-guest anchor; per-reservation segmentation is the optional `anchor_reservation_ref` plus the temporal `guest_conversation_anchored_to_reservation` link. Channel lives on `guest_message`, not here. Lifecycle `state` tracks the outermost outcome so operator UIs route on it; opt-out scope is the in-thread TCPA / WhatsApp / GDPR signal accumulator that the outbound-action validators honour.", "operationId": "get_hospitality_guest_conversation_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.guest_conversation" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_conversation:read" ] } ], "summary": "Read Guest conversation as of a watermark", "tags": [ "messaging" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.guest_conversation/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nPer-guest cross-channel conversation container. Two-level model per the 2026 vendor convergence: this object is the per-guest anchor; per-reservation segmentation is the optional `anchor_reservation_ref` plus the temporal `guest_conversation_anchored_to_reservation` link. Channel lives on `guest_message`, not here. Lifecycle `state` tracks the outermost outcome so operator UIs route on it; opt-out scope is the in-thread TCPA / WhatsApp / GDPR signal accumulator that the outbound-action validators honour.", "operationId": "list_links_hospitality_guest_conversation", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_conversation:read" ] } ], "summary": "List links of Guest conversation", "tags": [ "messaging" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.guest_conversation_anchored_to_reservation", "hospitality.link.guest_conversation_at_property", "hospitality.link.guest_conversation_for_person", "hospitality.link.guest_message_in_conversation", "hospitality.link.message_triage_chained_action_target", "hospitality.link.proposed_action_for_conversation" ] } } ] }, "/v1/object-types/hospitality.guest_conversation/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nPer-guest cross-channel conversation container. Two-level model per the 2026 vendor convergence: this object is the per-guest anchor; per-reservation segmentation is the optional `anchor_reservation_ref` plus the temporal `guest_conversation_anchored_to_reservation` link. Channel lives on `guest_message`, not here. Lifecycle `state` tracks the outermost outcome so operator UIs route on it; opt-out scope is the in-thread TCPA / WhatsApp / GDPR signal accumulator that the outbound-action validators honour.", "operationId": "traverse_hospitality_guest_conversation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.guest_conversation_anchored_to_reservation", "hospitality.link.guest_conversation_at_property", "hospitality.link.guest_conversation_for_person", "hospitality.link.guest_message_in_conversation", "hospitality.link.message_triage_chained_action_target", "hospitality.link.proposed_action_for_conversation" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_conversation:read" ] } ], "summary": "Traverse from Guest conversation", "tags": [ "messaging" ] } }, "/v1/object-types/hospitality.guest_conversation/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nPer-guest cross-channel conversation container. Two-level model per the 2026 vendor convergence: this object is the per-guest anchor; per-reservation segmentation is the optional `anchor_reservation_ref` plus the temporal `guest_conversation_anchored_to_reservation` link. Channel lives on `guest_message`, not here. Lifecycle `state` tracks the outermost outcome so operator UIs route on it; opt-out scope is the in-thread TCPA / WhatsApp / GDPR signal accumulator that the outbound-action validators honour.", "operationId": "search_hospitality_guest_conversation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "person_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.person" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_message_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_message_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_message_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_message_at_computed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_message_at_computed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_message_at_computed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "state" }, "type": { "const": "eq" }, "value": { "enum": [ "open", "awaiting_guest", "awaiting_staff", "closed_resolved", "closed_unresolved", "escalated" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "state_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "state_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "anchor_reservation_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "language" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "language" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "language" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "language" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "message_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "message_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "message_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "inbound_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "inbound_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "inbound_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "triage_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "triage_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "triage_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "escalation_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "escalation_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "escalation_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "message_count_computed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "message_count_computed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "message_count_computed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opt_out_scope" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "sms_marketing", "sms_all", "whatsapp_marketing", "email_marketing", "voice_all", "gdpr_erasure_requested" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "redactions_applied" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "pan", "cvv", "government_id", "health_disclosure", "child_safeguarding", "other_pii" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sentiment_trajectory" }, "type": { "const": "eq" }, "value": { "items": { "format": "decimal", "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "opened_at", "last_message_at", "last_message_at_computed_at", "state", "state_reason", "language", "message_count", "inbound_count", "triage_count", "escalation_count", "message_count_computed_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_conversation" }, "properties": { "additionalProperties": false, "properties": { "anchor_reservation_ref": { "format": "uuid", "title": "Optional reservation anchor (pre-arrival / in-house / departing)", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "escalation_count": { "title": "Count of triages that escalated (denormalised; §B.1)", "type": "integer" }, "id": { "title": "Conversation id", "type": "string" }, "inbound_count": { "title": "Count of inbound messages (denormalised; §B.1)", "type": "integer" }, "language": { "title": "BCP-47 tag of the guest's most recently detected reply language", "type": "string" }, "last_message_at": { "format": "date-time", "title": "Most recent message timestamp (denormalised, §B.1)", "type": "string" }, "last_message_at_computed_at": { "format": "date-time", "title": "Refresh-discipline pair for `last_message_at`", "type": "string" }, "message_count": { "title": "Count of messages in this conversation (denormalised; §B.1)", "type": "integer" }, "message_count_computed_at": { "format": "date-time", "title": "Refresh pair for the four counters (§B.1 discipline)", "type": "string" }, "opened_at": { "format": "date-time", "title": "When the conversation opened (first message timestamp)", "type": "string" }, "opt_out_scope": { "items": { "enum": [ "sms_marketing", "sms_all", "whatsapp_marketing", "email_marketing", "voice_all", "gdpr_erasure_requested" ], "type": "string" }, "title": "Opt-out signals received in-thread (TCPA / WhatsApp / GDPR)", "type": "array" }, "person_ref": { "format": "uuid", "title": "The guest (person) this conversation belongs to", "type": "string", "x-aerandil-references": "hospitality.person" }, "redactions_applied": { "items": { "enum": [ "pan", "cvv", "government_id", "health_disclosure", "child_safeguarding", "other_pii" ], "type": "string" }, "title": "Aggregated redaction-kind set across the conversation", "type": "array" }, "sentiment_trajectory": { "items": { "format": "decimal", "type": "string" }, "title": "Rolling sentiment scores [-1.0, 1.0] per message (bounded length)", "type": "array" }, "state": { "enum": [ "open", "awaiting_guest", "awaiting_staff", "closed_resolved", "closed_unresolved", "escalated" ], "title": "Lifecycle state", "type": "string" }, "state_reason": { "title": "Optional short reason on terminal state transitions", "type": "string" }, "triage_count": { "title": "Count of triages issued in this conversation (denormalised; §B.1)", "type": "integer" } }, "required": [ "id", "opened_at", "last_message_at", "state", "opt_out_scope", "redactions_applied" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_conversation:read" ] } ], "summary": "Search Guest conversation", "tags": [ "messaging" ] } }, "/v1/object-types/hospitality.guest_feedback/objects/{id}": { "get": { "description": "Read an existing instance.\n\nWhat a guest told the house — a `complaint`, a `compliment` or a `suggestion` (hubOS's guest feedback form) — and where the house has got to with it: `open` when recorded, `in_progress` once someone follows up (an entry on its thread, a work order raised from it), `resolved` with what the house did, `closed` when the case is finished. A complaint names its category. The feedback holds no guest name or contact: the guest (`guest_feedback_for_person`), the stay it is about (`guest_feedback_for_stay`) and the message it came from (`guest_feedback_from_message`) are links, and the guest's own words (`text`) are marked as the guest's. The thread is its `guest_feedback_entry` rows; `delegated_to_role` is the role the case is with. It is filed under the house's own labels (`labels`, `guest_feedback_has_label`) and, once the stay has departed, carries the guest's `checkout_satisfaction` (1–5).", "operationId": "get_hospitality_guest_feedback", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" }, "properties": { "additionalProperties": false, "properties": { "category": { "enum": [ "cleanliness", "noise", "billing", "service", "food", "maintenance", "other" ], "title": "What it is about (cleanliness, noise, billing, service, food, maintenance, other); required on a complaint", "type": "string" }, "channel": { "enum": [ "in_person", "phone", "survey", "review", "sms", "whatsapp", "email", "web_chat", "app_chat", "voice_ivr", "ota_inbox", "social_dm", "in_room_device", "other" ], "title": "How it reached the house: in person, by phone, a survey, a review, or the messaging channel of the message it came from", "type": "string" }, "checkout_satisfaction": { "title": "How satisfied the guest said they were at checkout, 1 (not at all) to 5 (very) — a departed stay's", "type": "integer" }, "checkout_satisfaction_at": { "format": "date-time", "title": "When the checkout satisfaction was recorded", "type": "string" }, "close_reason": { "title": "Why a complaint was closed without being resolved", "type": "string" }, "closed_at": { "format": "date-time", "title": "When the case was closed", "type": "string" }, "delegated_to_role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "The role the case is with (hubOS's delegated profile)", "type": "string" }, "id": { "title": "Guest feedback id", "type": "string" }, "kind": { "enum": [ "complaint", "compliment", "suggestion" ], "title": "Complaint, compliment or suggestion", "type": "string" }, "labels": { "items": { "type": "string" }, "title": "The codes of the house's labels it is filed under — the same set as its guest_feedback_has_label edges", "type": "array" }, "received_at": { "format": "date-time", "title": "When the guest gave it", "type": "string" }, "resolution": { "title": "What the house did about it", "type": "string" }, "resolved_at": { "format": "date-time", "title": "When it was resolved", "type": "string" }, "status": { "enum": [ "open", "in_progress", "resolved", "closed" ], "title": "Open, in progress, resolved or closed", "type": "string" }, "text": { "title": "What the guest said, in their words or the desk's summary of them", "type": "string" } }, "required": [ "id", "kind", "received_at", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_feedback:read" ] } ], "summary": "Read Guest feedback", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.guest_feedback/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nWhat a guest told the house — a `complaint`, a `compliment` or a `suggestion` (hubOS's guest feedback form) — and where the house has got to with it: `open` when recorded, `in_progress` once someone follows up (an entry on its thread, a work order raised from it), `resolved` with what the house did, `closed` when the case is finished. A complaint names its category. The feedback holds no guest name or contact: the guest (`guest_feedback_for_person`), the stay it is about (`guest_feedback_for_stay`) and the message it came from (`guest_feedback_from_message`) are links, and the guest's own words (`text`) are marked as the guest's. The thread is its `guest_feedback_entry` rows; `delegated_to_role` is the role the case is with. It is filed under the house's own labels (`labels`, `guest_feedback_has_label`) and, once the stay has departed, carries the guest's `checkout_satisfaction` (1–5).", "operationId": "get_hospitality_guest_feedback_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_feedback:read" ] } ], "summary": "Read Guest feedback as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.guest_feedback/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nWhat a guest told the house — a `complaint`, a `compliment` or a `suggestion` (hubOS's guest feedback form) — and where the house has got to with it: `open` when recorded, `in_progress` once someone follows up (an entry on its thread, a work order raised from it), `resolved` with what the house did, `closed` when the case is finished. A complaint names its category. The feedback holds no guest name or contact: the guest (`guest_feedback_for_person`), the stay it is about (`guest_feedback_for_stay`) and the message it came from (`guest_feedback_from_message`) are links, and the guest's own words (`text`) are marked as the guest's. The thread is its `guest_feedback_entry` rows; `delegated_to_role` is the role the case is with. It is filed under the house's own labels (`labels`, `guest_feedback_has_label`) and, once the stay has departed, carries the guest's `checkout_satisfaction` (1–5).", "operationId": "list_links_hospitality_guest_feedback", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_feedback:read" ] } ], "summary": "List links of Guest feedback", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.guest_feedback_entry_on_feedback", "hospitality.link.guest_feedback_for_person", "hospitality.link.guest_feedback_for_stay", "hospitality.link.guest_feedback_from_message", "hospitality.link.guest_feedback_has_label", "hospitality.link.stored_object_for_guest_feedback", "hospitality.link.work_order_answers_feedback" ] } } ] }, "/v1/object-types/hospitality.guest_feedback/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nWhat a guest told the house — a `complaint`, a `compliment` or a `suggestion` (hubOS's guest feedback form) — and where the house has got to with it: `open` when recorded, `in_progress` once someone follows up (an entry on its thread, a work order raised from it), `resolved` with what the house did, `closed` when the case is finished. A complaint names its category. The feedback holds no guest name or contact: the guest (`guest_feedback_for_person`), the stay it is about (`guest_feedback_for_stay`) and the message it came from (`guest_feedback_from_message`) are links, and the guest's own words (`text`) are marked as the guest's. The thread is its `guest_feedback_entry` rows; `delegated_to_role` is the role the case is with. It is filed under the house's own labels (`labels`, `guest_feedback_has_label`) and, once the stay has departed, carries the guest's `checkout_satisfaction` (1–5).", "operationId": "traverse_hospitality_guest_feedback", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.guest_feedback_entry_on_feedback", "hospitality.link.guest_feedback_for_person", "hospitality.link.guest_feedback_for_stay", "hospitality.link.guest_feedback_from_message", "hospitality.link.guest_feedback_has_label", "hospitality.link.stored_object_for_guest_feedback", "hospitality.link.work_order_answers_feedback" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_feedback:read" ] } ], "summary": "Traverse from Guest feedback", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.guest_feedback/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nWhat a guest told the house — a `complaint`, a `compliment` or a `suggestion` (hubOS's guest feedback form) — and where the house has got to with it: `open` when recorded, `in_progress` once someone follows up (an entry on its thread, a work order raised from it), `resolved` with what the house did, `closed` when the case is finished. A complaint names its category. The feedback holds no guest name or contact: the guest (`guest_feedback_for_person`), the stay it is about (`guest_feedback_for_stay`) and the message it came from (`guest_feedback_from_message`) are links, and the guest's own words (`text`) are marked as the guest's. The thread is its `guest_feedback_entry` rows; `delegated_to_role` is the role the case is with. It is filed under the house's own labels (`labels`, `guest_feedback_has_label`) and, once the stay has departed, carries the guest's `checkout_satisfaction` (1–5).", "operationId": "search_hospitality_guest_feedback", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "complaint", "compliment", "suggestion" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "category" }, "type": { "const": "eq" }, "value": { "enum": [ "cleanliness", "noise", "billing", "service", "food", "maintenance", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "received_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "received_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "received_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "channel" }, "type": { "const": "eq" }, "value": { "enum": [ "in_person", "phone", "survey", "review", "sms", "whatsapp", "email", "web_chat", "app_chat", "voice_ivr", "ota_inbox", "social_dm", "in_room_device", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "open", "in_progress", "resolved", "closed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delegated_to_role" }, "type": { "const": "eq" }, "value": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "resolution" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "resolution" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "resolved_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "resolved_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "resolved_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "close_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "close_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "labels" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checkout_satisfaction" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checkout_satisfaction" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checkout_satisfaction" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checkout_satisfaction_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checkout_satisfaction_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checkout_satisfaction_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "kind", "category", "text", "received_at", "channel", "status", "delegated_to_role", "resolution", "resolved_at", "closed_at", "close_reason", "checkout_satisfaction", "checkout_satisfaction_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback" }, "properties": { "additionalProperties": false, "properties": { "category": { "enum": [ "cleanliness", "noise", "billing", "service", "food", "maintenance", "other" ], "title": "What it is about (cleanliness, noise, billing, service, food, maintenance, other); required on a complaint", "type": "string" }, "channel": { "enum": [ "in_person", "phone", "survey", "review", "sms", "whatsapp", "email", "web_chat", "app_chat", "voice_ivr", "ota_inbox", "social_dm", "in_room_device", "other" ], "title": "How it reached the house: in person, by phone, a survey, a review, or the messaging channel of the message it came from", "type": "string" }, "checkout_satisfaction": { "title": "How satisfied the guest said they were at checkout, 1 (not at all) to 5 (very) — a departed stay's", "type": "integer" }, "checkout_satisfaction_at": { "format": "date-time", "title": "When the checkout satisfaction was recorded", "type": "string" }, "close_reason": { "title": "Why a complaint was closed without being resolved", "type": "string" }, "closed_at": { "format": "date-time", "title": "When the case was closed", "type": "string" }, "delegated_to_role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "The role the case is with (hubOS's delegated profile)", "type": "string" }, "id": { "title": "Guest feedback id", "type": "string" }, "kind": { "enum": [ "complaint", "compliment", "suggestion" ], "title": "Complaint, compliment or suggestion", "type": "string" }, "labels": { "items": { "type": "string" }, "title": "The codes of the house's labels it is filed under — the same set as its guest_feedback_has_label edges", "type": "array" }, "received_at": { "format": "date-time", "title": "When the guest gave it", "type": "string" }, "resolution": { "title": "What the house did about it", "type": "string" }, "resolved_at": { "format": "date-time", "title": "When it was resolved", "type": "string" }, "status": { "enum": [ "open", "in_progress", "resolved", "closed" ], "title": "Open, in progress, resolved or closed", "type": "string" }, "text": { "title": "What the guest said, in their words or the desk's summary of them", "type": "string" } }, "required": [ "id", "kind", "received_at", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_feedback:read" ] } ], "summary": "Search Guest feedback", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.guest_feedback_entry/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne follow-up on a piece of guest feedback, written for an `internal` audience (the house to itself: `internal_text`, read on the floor) or the `guest` (`guest_text`, marked as the guest's) — hubOS's thread, which keeps the internal and the guest follow-up as separate texts. A guest entry is sent into the guest's open conversation at the house as a reply (`guest_feedback_entry_sent_as` names the message); when there is none, or the guest has said not to be written to, the entry is the record and `undelivered_reason` says why it was not sent. An entry may hand the case to a role (`delegated_to_role`). Written once; the author is the staff member linked by `guest_feedback_entry_by_staff`, or the principal on the entry's event.", "operationId": "get_hospitality_guest_feedback_entry", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback_entry" }, "properties": { "additionalProperties": false, "properties": { "audience": { "enum": [ "internal", "guest" ], "title": "Internal (the house to itself) or guest (what the guest was told)", "type": "string" }, "delegated_to_role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "The role this entry handed the case to", "type": "string" }, "guest_text": { "title": "What the guest was told — set on a guest entry only", "type": "string" }, "id": { "title": "Guest feedback entry id", "type": "string" }, "internal_text": { "title": "The internal follow-up — set on an internal entry only", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When the follow-up was written", "type": "string" }, "undelivered_reason": { "title": "Why a guest entry was not sent to the guest", "type": "string" } }, "required": [ "id", "audience", "recorded_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_feedback_entry:read" ] } ], "summary": "Read Guest feedback entry", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.guest_feedback_entry/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne follow-up on a piece of guest feedback, written for an `internal` audience (the house to itself: `internal_text`, read on the floor) or the `guest` (`guest_text`, marked as the guest's) — hubOS's thread, which keeps the internal and the guest follow-up as separate texts. A guest entry is sent into the guest's open conversation at the house as a reply (`guest_feedback_entry_sent_as` names the message); when there is none, or the guest has said not to be written to, the entry is the record and `undelivered_reason` says why it was not sent. An entry may hand the case to a role (`delegated_to_role`). Written once; the author is the staff member linked by `guest_feedback_entry_by_staff`, or the principal on the entry's event.", "operationId": "get_hospitality_guest_feedback_entry_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback_entry" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_feedback_entry:read" ] } ], "summary": "Read Guest feedback entry as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.guest_feedback_entry/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne follow-up on a piece of guest feedback, written for an `internal` audience (the house to itself: `internal_text`, read on the floor) or the `guest` (`guest_text`, marked as the guest's) — hubOS's thread, which keeps the internal and the guest follow-up as separate texts. A guest entry is sent into the guest's open conversation at the house as a reply (`guest_feedback_entry_sent_as` names the message); when there is none, or the guest has said not to be written to, the entry is the record and `undelivered_reason` says why it was not sent. An entry may hand the case to a role (`delegated_to_role`). Written once; the author is the staff member linked by `guest_feedback_entry_by_staff`, or the principal on the entry's event.", "operationId": "list_links_hospitality_guest_feedback_entry", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_feedback_entry:read" ] } ], "summary": "List links of Guest feedback entry", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.guest_feedback_entry_by_staff", "hospitality.link.guest_feedback_entry_on_feedback", "hospitality.link.guest_feedback_entry_sent_as" ] } } ] }, "/v1/object-types/hospitality.guest_feedback_entry/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne follow-up on a piece of guest feedback, written for an `internal` audience (the house to itself: `internal_text`, read on the floor) or the `guest` (`guest_text`, marked as the guest's) — hubOS's thread, which keeps the internal and the guest follow-up as separate texts. A guest entry is sent into the guest's open conversation at the house as a reply (`guest_feedback_entry_sent_as` names the message); when there is none, or the guest has said not to be written to, the entry is the record and `undelivered_reason` says why it was not sent. An entry may hand the case to a role (`delegated_to_role`). Written once; the author is the staff member linked by `guest_feedback_entry_by_staff`, or the principal on the entry's event.", "operationId": "traverse_hospitality_guest_feedback_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.guest_feedback_entry_by_staff", "hospitality.link.guest_feedback_entry_on_feedback", "hospitality.link.guest_feedback_entry_sent_as" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_feedback_entry:read" ] } ], "summary": "Traverse from Guest feedback entry", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.guest_feedback_entry/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne follow-up on a piece of guest feedback, written for an `internal` audience (the house to itself: `internal_text`, read on the floor) or the `guest` (`guest_text`, marked as the guest's) — hubOS's thread, which keeps the internal and the guest follow-up as separate texts. A guest entry is sent into the guest's open conversation at the house as a reply (`guest_feedback_entry_sent_as` names the message); when there is none, or the guest has said not to be written to, the entry is the record and `undelivered_reason` says why it was not sent. An entry may hand the case to a role (`delegated_to_role`). Written once; the author is the staff member linked by `guest_feedback_entry_by_staff`, or the principal on the entry's event.", "operationId": "search_hospitality_guest_feedback_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "audience" }, "type": { "const": "eq" }, "value": { "enum": [ "internal", "guest" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "internal_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "internal_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "guest_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "guest_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delegated_to_role" }, "type": { "const": "eq" }, "value": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "undelivered_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "undelivered_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "audience", "internal_text", "guest_text", "recorded_at", "delegated_to_role", "undelivered_reason" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_feedback_entry" }, "properties": { "additionalProperties": false, "properties": { "audience": { "enum": [ "internal", "guest" ], "title": "Internal (the house to itself) or guest (what the guest was told)", "type": "string" }, "delegated_to_role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "The role this entry handed the case to", "type": "string" }, "guest_text": { "title": "What the guest was told — set on a guest entry only", "type": "string" }, "id": { "title": "Guest feedback entry id", "type": "string" }, "internal_text": { "title": "The internal follow-up — set on an internal entry only", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When the follow-up was written", "type": "string" }, "undelivered_reason": { "title": "Why a guest entry was not sent to the guest", "type": "string" } }, "required": [ "id", "audience", "recorded_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_feedback_entry:read" ] } ], "summary": "Search Guest feedback entry", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.guest_id_document/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA minimal government-ID record captured for statutory guest registration — document type, issuing country, expiry, and a verification result. The raw number / scan is never stored; it stays in an external vault reached via `guest_id_document_references_external_record`.", "operationId": "get_hospitality_guest_id_document", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_id_document" }, "properties": { "additionalProperties": false, "properties": { "captured_at": { "format": "date-time", "title": "Captured at", "type": "string" }, "document_number_last4": { "title": "Last 4 glyphs of the document number (never the full number)", "type": "string" }, "document_type": { "enum": [ "passport", "visa", "national_id", "drivers_licence", "residence_permit" ], "title": "Document type", "type": "string" }, "expiry_date": { "format": "date", "title": "Document expiry date", "type": "string" }, "holder_name": { "title": "Holder name as printed", "type": "string" }, "id": { "title": "Document record id", "type": "string" }, "issuing_country": { "title": "Issuing country (ISO 3166-1 alpha-2)", "type": "string" }, "retain_until": { "format": "date", "title": "Retain-until (storage-limitation clock)", "type": "string" }, "verification_method": { "enum": [ "manual_visual", "document_scan", "nfc_chip", "third_party_idv", "government_registry" ], "title": "Verification method", "type": "string" }, "verification_status": { "enum": [ "unverified", "verified", "failed", "expired" ], "title": "Verification status", "type": "string" }, "verified_at": { "format": "date-time", "title": "Verified at", "type": "string" } }, "required": [ "id", "verification_status", "captured_at", "retain_until" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_id_document:read" ] } ], "summary": "Read Guest ID document", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.guest_id_document/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA minimal government-ID record captured for statutory guest registration — document type, issuing country, expiry, and a verification result. The raw number / scan is never stored; it stays in an external vault reached via `guest_id_document_references_external_record`.", "operationId": "get_hospitality_guest_id_document_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.guest_id_document" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_id_document:read" ] } ], "summary": "Read Guest ID document as of a watermark", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.guest_id_document/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA minimal government-ID record captured for statutory guest registration — document type, issuing country, expiry, and a verification result. The raw number / scan is never stored; it stays in an external vault reached via `guest_id_document_references_external_record`.", "operationId": "list_links_hospitality_guest_id_document", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_id_document:read" ] } ], "summary": "List links of Guest ID document", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.guest_id_document_for_person", "hospitality.link.guest_id_document_references_external_record" ] } } ] }, "/v1/object-types/hospitality.guest_id_document/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA minimal government-ID record captured for statutory guest registration — document type, issuing country, expiry, and a verification result. The raw number / scan is never stored; it stays in an external vault reached via `guest_id_document_references_external_record`.", "operationId": "traverse_hospitality_guest_id_document", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.guest_id_document_for_person", "hospitality.link.guest_id_document_references_external_record" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_id_document:read" ] } ], "summary": "Traverse from Guest ID document", "tags": [ "people" ] } }, "/v1/object-types/hospitality.guest_id_document/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA minimal government-ID record captured for statutory guest registration — document type, issuing country, expiry, and a verification result. The raw number / scan is never stored; it stays in an external vault reached via `guest_id_document_references_external_record`.", "operationId": "search_hospitality_guest_id_document", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "document_type" }, "type": { "const": "eq" }, "value": { "enum": [ "passport", "visa", "national_id", "drivers_licence", "residence_permit" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issuing_country" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issuing_country" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issuing_country" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issuing_country" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "holder_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "holder_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "holder_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "holder_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "document_number_last4" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "document_number_last4" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "document_number_last4" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "document_number_last4" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expiry_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expiry_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expiry_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "verification_status" }, "type": { "const": "eq" }, "value": { "enum": [ "unverified", "verified", "failed", "expired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "verification_method" }, "type": { "const": "eq" }, "value": { "enum": [ "manual_visual", "document_scan", "nfc_chip", "third_party_idv", "government_registry" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "verified_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "verified_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "verified_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "captured_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "captured_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "captured_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retain_until" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retain_until" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retain_until" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "document_type", "issuing_country", "holder_name", "document_number_last4", "expiry_date", "verification_status", "verification_method", "verified_at", "captured_at", "retain_until" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_id_document" }, "properties": { "additionalProperties": false, "properties": { "captured_at": { "format": "date-time", "title": "Captured at", "type": "string" }, "document_number_last4": { "title": "Last 4 glyphs of the document number (never the full number)", "type": "string" }, "document_type": { "enum": [ "passport", "visa", "national_id", "drivers_licence", "residence_permit" ], "title": "Document type", "type": "string" }, "expiry_date": { "format": "date", "title": "Document expiry date", "type": "string" }, "holder_name": { "title": "Holder name as printed", "type": "string" }, "id": { "title": "Document record id", "type": "string" }, "issuing_country": { "title": "Issuing country (ISO 3166-1 alpha-2)", "type": "string" }, "retain_until": { "format": "date", "title": "Retain-until (storage-limitation clock)", "type": "string" }, "verification_method": { "enum": [ "manual_visual", "document_scan", "nfc_chip", "third_party_idv", "government_registry" ], "title": "Verification method", "type": "string" }, "verification_status": { "enum": [ "unverified", "verified", "failed", "expired" ], "title": "Verification status", "type": "string" }, "verified_at": { "format": "date-time", "title": "Verified at", "type": "string" } }, "required": [ "id", "verification_status", "captured_at", "retain_until" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_id_document:read" ] } ], "summary": "Search Guest ID document", "tags": [ "people" ] } }, "/v1/object-types/hospitality.guest_message/objects/{id}": { "get": { "description": "Read an existing instance.\n\nTyped shadow of a single inbound or outbound message. The full payload lives in the external messaging system (Twilio, WhatsApp Business, Mews Conversations, HiJiffy / Canary inbox, OTA Messaging API, voice-IVR transcript store); Aerandil holds the audit-grade decision-time fields plus an optional `external_record_reference` pointer to the full content. PCI-DSS 4.0 hard-validator-enforced: no Luhn-matching digit sequence may appear in `redacted_excerpt`. The `content_hash` is the tamper-evidence anchor.", "operationId": "get_hospitality_guest_message", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_message" }, "properties": { "additionalProperties": false, "properties": { "author_kind": { "enum": [ "guest", "staff_human", "staff_agent", "system" ], "title": "Who composed the message (guest / staff_human / staff_agent / system)", "type": "string" }, "author_principal": { "title": "`principal.stable_id()` of the author when not the guest", "type": "string" }, "channel": { "enum": [ "sms", "whatsapp", "email", "web_chat", "app_chat", "voice_ivr", "ota_inbox", "social_dm", "in_room_device", "other" ], "title": "Communication channel", "type": "string" }, "channel_thread_id": { "title": "External system thread identifier (Booking.com conversation_id, Twilio MessageSid, WhatsApp wamid, etc.)", "type": "string" }, "content_hash": { "title": "SHA-256 of the original message bytes (tamper-evidence)", "type": "string" }, "conversation_ref": { "format": "uuid", "title": "The conversation container", "type": "string", "x-aerandil-references": "hospitality.guest_conversation" }, "delivery_address": { "title": "The phone number or email address the message goes to, resolved when it was recorded", "type": "string" }, "delivery_attempted_at": { "format": "date-time", "title": "When the adapter last tried to send it", "type": "string" }, "delivery_attempts": { "title": "How many times the adapter has tried to send it", "type": "integer" }, "delivery_error": { "title": "Why the last send failed, in words the desk can act on", "type": "string" }, "delivery_state": { "enum": [ "queued", "sending", "sent", "failed" ], "title": "Where the kernel's own send stands: queued, sending (claimed by the worker), sent, or failed", "type": "string" }, "detected_language": { "title": "BCP-47 — may differ from `conversation.language` (mid-thread switches)", "type": "string" }, "direction": { "enum": [ "inbound", "outbound" ], "title": "Inbound (from guest) or outbound (to guest)", "type": "string" }, "id": { "title": "Message id", "type": "string" }, "ingress_principal": { "title": "`principal.stable_id()` of the service or human that recorded the message", "type": "string" }, "purpose": { "enum": [ "reply", "service", "marketing", "waitlist_offer", "payment_request", "card_refused" ], "title": "Why the house wrote: a reply, a service message, marketing, or a waitlist offer", "type": "string" }, "received_at": { "format": "date-time", "title": "When the message arrived (inbound) or was sent (outbound)", "type": "string" }, "redacted_excerpt": { "title": "PII-stripped excerpt for the audit trail (default cap 280 chars)", "type": "string" }, "redactions_applied": { "items": { "enum": [ "pan", "cvv", "government_id", "health_disclosure", "child_safeguarding", "other_pii" ], "type": "string" }, "title": "Per-message redaction kinds", "type": "array" }, "template_id": { "title": "WhatsApp Business template id (required outside the 24-hour service window)", "type": "string" }, "vendor_message_id": { "title": "The delivery vendor's id for the send (Twilio MessageSid, SMTP Message-ID)", "type": "string" }, "waitlist_entry_ref": { "format": "uuid", "title": "The waitlist entry whose offer this message carries; its claim token is minted when the message is sent", "type": "string", "x-aerandil-references": "hospitality.waitlist_entry" }, "word_count": { "title": "Optional word count (triage-cost analytics)", "type": "integer" } }, "required": [ "id", "conversation_ref", "channel", "direction", "received_at", "redactions_applied" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_message:read" ] } ], "summary": "Read Guest message", "tags": [ "messaging" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.guest_message/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nTyped shadow of a single inbound or outbound message. The full payload lives in the external messaging system (Twilio, WhatsApp Business, Mews Conversations, HiJiffy / Canary inbox, OTA Messaging API, voice-IVR transcript store); Aerandil holds the audit-grade decision-time fields plus an optional `external_record_reference` pointer to the full content. PCI-DSS 4.0 hard-validator-enforced: no Luhn-matching digit sequence may appear in `redacted_excerpt`. The `content_hash` is the tamper-evidence anchor.", "operationId": "get_hospitality_guest_message_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.guest_message" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_message:read" ] } ], "summary": "Read Guest message as of a watermark", "tags": [ "messaging" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.guest_message/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nTyped shadow of a single inbound or outbound message. The full payload lives in the external messaging system (Twilio, WhatsApp Business, Mews Conversations, HiJiffy / Canary inbox, OTA Messaging API, voice-IVR transcript store); Aerandil holds the audit-grade decision-time fields plus an optional `external_record_reference` pointer to the full content. PCI-DSS 4.0 hard-validator-enforced: no Luhn-matching digit sequence may appear in `redacted_excerpt`. The `content_hash` is the tamper-evidence anchor.", "operationId": "list_links_hospitality_guest_message", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_message:read" ] } ], "summary": "List links of Guest message", "tags": [ "messaging" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.guest_feedback_entry_sent_as", "hospitality.link.guest_feedback_from_message", "hospitality.link.guest_message_in_conversation", "hospitality.link.guest_message_references_external_record", "hospitality.link.message_triage_for_message" ] } } ] }, "/v1/object-types/hospitality.guest_message/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nTyped shadow of a single inbound or outbound message. The full payload lives in the external messaging system (Twilio, WhatsApp Business, Mews Conversations, HiJiffy / Canary inbox, OTA Messaging API, voice-IVR transcript store); Aerandil holds the audit-grade decision-time fields plus an optional `external_record_reference` pointer to the full content. PCI-DSS 4.0 hard-validator-enforced: no Luhn-matching digit sequence may appear in `redacted_excerpt`. The `content_hash` is the tamper-evidence anchor.", "operationId": "traverse_hospitality_guest_message", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.guest_feedback_entry_sent_as", "hospitality.link.guest_feedback_from_message", "hospitality.link.guest_message_in_conversation", "hospitality.link.guest_message_references_external_record", "hospitality.link.message_triage_for_message" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_message:read" ] } ], "summary": "Traverse from Guest message", "tags": [ "messaging" ] } }, "/v1/object-types/hospitality.guest_message/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nTyped shadow of a single inbound or outbound message. The full payload lives in the external messaging system (Twilio, WhatsApp Business, Mews Conversations, HiJiffy / Canary inbox, OTA Messaging API, voice-IVR transcript store); Aerandil holds the audit-grade decision-time fields plus an optional `external_record_reference` pointer to the full content. PCI-DSS 4.0 hard-validator-enforced: no Luhn-matching digit sequence may appear in `redacted_excerpt`. The `content_hash` is the tamper-evidence anchor.", "operationId": "search_hospitality_guest_message", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "conversation_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.guest_conversation" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "channel" }, "type": { "const": "eq" }, "value": { "enum": [ "sms", "whatsapp", "email", "web_chat", "app_chat", "voice_ivr", "ota_inbox", "social_dm", "in_room_device", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "channel_thread_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "channel_thread_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "channel_thread_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "channel_thread_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "direction" }, "type": { "const": "eq" }, "value": { "enum": [ "inbound", "outbound" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "received_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "received_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "received_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "author_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "guest", "staff_human", "staff_agent", "system" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "author_principal" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "author_principal" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "author_principal" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "author_principal" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "redacted_excerpt" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "redacted_excerpt" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "content_hash" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "content_hash" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "content_hash" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "content_hash" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "word_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "word_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "word_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "detected_language" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "detected_language" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "detected_language" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "detected_language" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "redactions_applied" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "pan", "cvv", "government_id", "health_disclosure", "child_safeguarding", "other_pii" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ingress_principal" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ingress_principal" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ingress_principal" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ingress_principal" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "template_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "template_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "template_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "template_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "purpose" }, "type": { "const": "eq" }, "value": { "enum": [ "reply", "service", "marketing", "waitlist_offer", "payment_request", "card_refused" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delivery_state" }, "type": { "const": "eq" }, "value": { "enum": [ "queued", "sending", "sent", "failed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delivery_address" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delivery_address" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delivery_address" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delivery_address" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor_message_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor_message_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor_message_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor_message_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delivery_attempted_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delivery_attempted_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delivery_attempted_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delivery_attempts" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delivery_attempts" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delivery_attempts" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delivery_error" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delivery_error" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waitlist_entry_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.waitlist_entry" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "channel", "channel_thread_id", "direction", "received_at", "author_kind", "author_principal", "redacted_excerpt", "content_hash", "word_count", "detected_language", "ingress_principal", "template_id", "purpose", "delivery_state", "delivery_address", "vendor_message_id", "delivery_attempted_at", "delivery_attempts", "delivery_error" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.guest_message" }, "properties": { "additionalProperties": false, "properties": { "author_kind": { "enum": [ "guest", "staff_human", "staff_agent", "system" ], "title": "Who composed the message (guest / staff_human / staff_agent / system)", "type": "string" }, "author_principal": { "title": "`principal.stable_id()` of the author when not the guest", "type": "string" }, "channel": { "enum": [ "sms", "whatsapp", "email", "web_chat", "app_chat", "voice_ivr", "ota_inbox", "social_dm", "in_room_device", "other" ], "title": "Communication channel", "type": "string" }, "channel_thread_id": { "title": "External system thread identifier (Booking.com conversation_id, Twilio MessageSid, WhatsApp wamid, etc.)", "type": "string" }, "content_hash": { "title": "SHA-256 of the original message bytes (tamper-evidence)", "type": "string" }, "conversation_ref": { "format": "uuid", "title": "The conversation container", "type": "string", "x-aerandil-references": "hospitality.guest_conversation" }, "delivery_address": { "title": "The phone number or email address the message goes to, resolved when it was recorded", "type": "string" }, "delivery_attempted_at": { "format": "date-time", "title": "When the adapter last tried to send it", "type": "string" }, "delivery_attempts": { "title": "How many times the adapter has tried to send it", "type": "integer" }, "delivery_error": { "title": "Why the last send failed, in words the desk can act on", "type": "string" }, "delivery_state": { "enum": [ "queued", "sending", "sent", "failed" ], "title": "Where the kernel's own send stands: queued, sending (claimed by the worker), sent, or failed", "type": "string" }, "detected_language": { "title": "BCP-47 — may differ from `conversation.language` (mid-thread switches)", "type": "string" }, "direction": { "enum": [ "inbound", "outbound" ], "title": "Inbound (from guest) or outbound (to guest)", "type": "string" }, "id": { "title": "Message id", "type": "string" }, "ingress_principal": { "title": "`principal.stable_id()` of the service or human that recorded the message", "type": "string" }, "purpose": { "enum": [ "reply", "service", "marketing", "waitlist_offer", "payment_request", "card_refused" ], "title": "Why the house wrote: a reply, a service message, marketing, or a waitlist offer", "type": "string" }, "received_at": { "format": "date-time", "title": "When the message arrived (inbound) or was sent (outbound)", "type": "string" }, "redacted_excerpt": { "title": "PII-stripped excerpt for the audit trail (default cap 280 chars)", "type": "string" }, "redactions_applied": { "items": { "enum": [ "pan", "cvv", "government_id", "health_disclosure", "child_safeguarding", "other_pii" ], "type": "string" }, "title": "Per-message redaction kinds", "type": "array" }, "template_id": { "title": "WhatsApp Business template id (required outside the 24-hour service window)", "type": "string" }, "vendor_message_id": { "title": "The delivery vendor's id for the send (Twilio MessageSid, SMTP Message-ID)", "type": "string" }, "waitlist_entry_ref": { "format": "uuid", "title": "The waitlist entry whose offer this message carries; its claim token is minted when the message is sent", "type": "string", "x-aerandil-references": "hospitality.waitlist_entry" }, "word_count": { "title": "Optional word count (triage-cost analytics)", "type": "integer" } }, "required": [ "id", "conversation_ref", "channel", "direction", "received_at", "redactions_applied" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.guest_message:read" ] } ], "summary": "Search Guest message", "tags": [ "messaging" ] } }, "/v1/object-types/hospitality.housekeeping_briefing/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe day's instructions from the head housekeeper to the floor — hubOS's 'indications', per building, user and date. One house (`housekeeping_briefing_at_property`), one business date, one author (`housekeeping_briefing_by`), the text. A second post the same day is a second briefing, not an edit; readers list a day's briefings newest first by `posted_at`.", "operationId": "get_hospitality_housekeeping_briefing", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_briefing" }, "properties": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "The house's day the briefing is for", "type": "string" }, "id": { "title": "Briefing id", "type": "string" }, "posted_at": { "format": "date-time", "title": "When it was posted", "type": "string" }, "text": { "title": "The instructions", "type": "string" } }, "required": [ "id", "business_date", "text", "posted_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.housekeeping_briefing:read" ] } ], "summary": "Read Housekeeping briefing", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.housekeeping_briefing/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe day's instructions from the head housekeeper to the floor — hubOS's 'indications', per building, user and date. One house (`housekeeping_briefing_at_property`), one business date, one author (`housekeeping_briefing_by`), the text. A second post the same day is a second briefing, not an edit; readers list a day's briefings newest first by `posted_at`.", "operationId": "get_hospitality_housekeeping_briefing_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_briefing" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.housekeeping_briefing:read" ] } ], "summary": "Read Housekeeping briefing as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.housekeeping_briefing/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe day's instructions from the head housekeeper to the floor — hubOS's 'indications', per building, user and date. One house (`housekeeping_briefing_at_property`), one business date, one author (`housekeeping_briefing_by`), the text. A second post the same day is a second briefing, not an edit; readers list a day's briefings newest first by `posted_at`.", "operationId": "list_links_hospitality_housekeeping_briefing", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.housekeeping_briefing:read" ] } ], "summary": "List links of Housekeeping briefing", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.housekeeping_briefing_at_property", "hospitality.link.housekeeping_briefing_by" ] } } ] }, "/v1/object-types/hospitality.housekeeping_briefing/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe day's instructions from the head housekeeper to the floor — hubOS's 'indications', per building, user and date. One house (`housekeeping_briefing_at_property`), one business date, one author (`housekeeping_briefing_by`), the text. A second post the same day is a second briefing, not an edit; readers list a day's briefings newest first by `posted_at`.", "operationId": "traverse_hospitality_housekeeping_briefing", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.housekeeping_briefing_at_property", "hospitality.link.housekeeping_briefing_by" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.housekeeping_briefing:read" ] } ], "summary": "Traverse from Housekeeping briefing", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.housekeeping_briefing/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe day's instructions from the head housekeeper to the floor — hubOS's 'indications', per building, user and date. One house (`housekeeping_briefing_at_property`), one business date, one author (`housekeeping_briefing_by`), the text. A second post the same day is a second briefing, not an edit; readers list a day's briefings newest first by `posted_at`.", "operationId": "search_hospitality_housekeeping_briefing", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "posted_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "posted_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "posted_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "business_date", "text", "posted_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_briefing" }, "properties": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "The house's day the briefing is for", "type": "string" }, "id": { "title": "Briefing id", "type": "string" }, "posted_at": { "format": "date-time", "title": "When it was posted", "type": "string" }, "text": { "title": "The instructions", "type": "string" } }, "required": [ "id", "business_date", "text", "posted_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.housekeeping_briefing:read" ] } ], "summary": "Search Housekeeping briefing", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.housekeeping_credit_rule/objects/{id}": { "get": { "description": "Read an existing instance.\n\nWhat one kind of housekeeping task is worth at a property (OPERA's housekeeping credits; the unit of hubOS's pacing report): `credits` — the workload unit a supervisor balances attendants' sheets in and an attendant's shift target is counted in — and optionally `standard_minutes`, what the work should take, against which the pacing report measures each cleaning's deviation. Keyed by (task type, room type): a rule naming a room type prices that task type in rooms of that type, a rule naming none prices it in every other room. Task creation stamps the most specific active rule's figures onto the task (`create_housekeeping_task`, `generate_housekeeping_tasks`), so a task keeps what it was worth when minted. Retiring a rule prices nothing new; authoring its key again revives it.", "operationId": "get_hospitality_housekeeping_credit_rule", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_credit_rule" }, "properties": { "additionalProperties": false, "properties": { "credits": { "format": "decimal", "title": "Credits one task of this kind is worth (zero or more)", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "id": { "title": "Housekeeping credit rule id", "type": "string" }, "retired_at": { "format": "date-time", "title": "When the rule was retired", "type": "string" }, "room_type_id": { "format": "uuid", "title": "The room type this rule prices the task type in; absent = every room type without a rule of its own", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "standard_minutes": { "title": "Minutes the work should take (1 to 1440); the pacing report's deviation is measured against it", "type": "integer" }, "status": { "enum": [ "active", "retired" ], "title": "Active (prices new tasks) or retired", "type": "string" }, "task_type": { "enum": [ "stayover", "departure", "vacant_pickup", "deep_clean", "turndown", "inspection", "public_area_clean", "public_area_inspection", "minibar", "laundry" ], "title": "The task type this rule prices", "type": "string" } }, "required": [ "id", "task_type", "credits", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.housekeeping_credit_rule:read" ] } ], "summary": "Read Housekeeping credit rule", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.housekeeping_credit_rule/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nWhat one kind of housekeeping task is worth at a property (OPERA's housekeeping credits; the unit of hubOS's pacing report): `credits` — the workload unit a supervisor balances attendants' sheets in and an attendant's shift target is counted in — and optionally `standard_minutes`, what the work should take, against which the pacing report measures each cleaning's deviation. Keyed by (task type, room type): a rule naming a room type prices that task type in rooms of that type, a rule naming none prices it in every other room. Task creation stamps the most specific active rule's figures onto the task (`create_housekeeping_task`, `generate_housekeeping_tasks`), so a task keeps what it was worth when minted. Retiring a rule prices nothing new; authoring its key again revives it.", "operationId": "get_hospitality_housekeeping_credit_rule_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_credit_rule" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.housekeeping_credit_rule:read" ] } ], "summary": "Read Housekeeping credit rule as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.housekeeping_credit_rule/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nWhat one kind of housekeeping task is worth at a property (OPERA's housekeeping credits; the unit of hubOS's pacing report): `credits` — the workload unit a supervisor balances attendants' sheets in and an attendant's shift target is counted in — and optionally `standard_minutes`, what the work should take, against which the pacing report measures each cleaning's deviation. Keyed by (task type, room type): a rule naming a room type prices that task type in rooms of that type, a rule naming none prices it in every other room. Task creation stamps the most specific active rule's figures onto the task (`create_housekeeping_task`, `generate_housekeeping_tasks`), so a task keeps what it was worth when minted. Retiring a rule prices nothing new; authoring its key again revives it.", "operationId": "list_links_hospitality_housekeeping_credit_rule", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.housekeeping_credit_rule:read" ] } ], "summary": "List links of Housekeeping credit rule", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.housekeeping_credit_rule_at_property" ] } } ] }, "/v1/object-types/hospitality.housekeeping_credit_rule/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nWhat one kind of housekeeping task is worth at a property (OPERA's housekeeping credits; the unit of hubOS's pacing report): `credits` — the workload unit a supervisor balances attendants' sheets in and an attendant's shift target is counted in — and optionally `standard_minutes`, what the work should take, against which the pacing report measures each cleaning's deviation. Keyed by (task type, room type): a rule naming a room type prices that task type in rooms of that type, a rule naming none prices it in every other room. Task creation stamps the most specific active rule's figures onto the task (`create_housekeeping_task`, `generate_housekeeping_tasks`), so a task keeps what it was worth when minted. Retiring a rule prices nothing new; authoring its key again revives it.", "operationId": "traverse_hospitality_housekeeping_credit_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.housekeeping_credit_rule_at_property" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.housekeeping_credit_rule:read" ] } ], "summary": "Traverse from Housekeeping credit rule", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.housekeeping_credit_rule/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nWhat one kind of housekeeping task is worth at a property (OPERA's housekeeping credits; the unit of hubOS's pacing report): `credits` — the workload unit a supervisor balances attendants' sheets in and an attendant's shift target is counted in — and optionally `standard_minutes`, what the work should take, against which the pacing report measures each cleaning's deviation. Keyed by (task type, room type): a rule naming a room type prices that task type in rooms of that type, a rule naming none prices it in every other room. Task creation stamps the most specific active rule's figures onto the task (`create_housekeeping_task`, `generate_housekeeping_tasks`), so a task keeps what it was worth when minted. Retiring a rule prices nothing new; authoring its key again revives it.", "operationId": "search_hospitality_housekeeping_credit_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "task_type" }, "type": { "const": "eq" }, "value": { "enum": [ "stayover", "departure", "vacant_pickup", "deep_clean", "turndown", "inspection", "public_area_clean", "public_area_inspection", "minibar", "laundry" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "room_type_id" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.room_type" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "credits" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "credits" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "credits" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "standard_minutes" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "standard_minutes" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "standard_minutes" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "retired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "task_type", "credits", "standard_minutes", "status", "retired_at", "description" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_credit_rule" }, "properties": { "additionalProperties": false, "properties": { "credits": { "format": "decimal", "title": "Credits one task of this kind is worth (zero or more)", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "id": { "title": "Housekeeping credit rule id", "type": "string" }, "retired_at": { "format": "date-time", "title": "When the rule was retired", "type": "string" }, "room_type_id": { "format": "uuid", "title": "The room type this rule prices the task type in; absent = every room type without a rule of its own", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "standard_minutes": { "title": "Minutes the work should take (1 to 1440); the pacing report's deviation is measured against it", "type": "integer" }, "status": { "enum": [ "active", "retired" ], "title": "Active (prices new tasks) or retired", "type": "string" }, "task_type": { "enum": [ "stayover", "departure", "vacant_pickup", "deep_clean", "turndown", "inspection", "public_area_clean", "public_area_inspection", "minibar", "laundry" ], "title": "The task type this rule prices", "type": "string" } }, "required": [ "id", "task_type", "credits", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.housekeeping_credit_rule:read" ] } ], "summary": "Search Housekeeping credit rule", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.housekeeping_task/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA unit of housekeeping work attached to a room: a stayover clean, a departure clean, a deep clean, a turndown, an inspection. Minted by `generate_housekeeping_tasks` (which derives the day's board from occupancy + due-outs and stamps a `generation_key` so re-runs converge) or by `create_housekeeping_task` for ad-hoc work (`origin` says which, and marks a failed inspection's re-clean). Assignment is the `housekeeping_task_assigned_to` edge; the per-attendant task sheet is a projection over (assignee, business_date), never a second object to keep in sync. A public area's work (2026-10-14) is the same object linked `housekeeping_task_for_area` instead of to a room — a task is for a room or an area, never both, and the `public_area_*` types are an area's alone; and a task may be assigned to a `worker_group` (`housekeeping_task_assigned_to_group`) instead of a person, until a member starts it. A task is also a request (2026-10-15): `requested_by` says who asked (a guest's request links the stay, `housekeeping_task_requested_by_stay`), `due_at` when it is due, and it carries a thread of notes (`housekeeping_task_entry`). `area_id`, `assignee_id` and `group_id` copy the area, person and group edges onto the row.", "operationId": "get_hospitality_housekeeping_task", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" }, "properties": { "additionalProperties": false, "properties": { "area_id": { "title": "The public area the task is for (its object id) — the housekeeping_task_for_area edge's target; absent on a room's task", "type": "string" }, "assignee_id": { "title": "The staff member who holds the task (their object id) — the housekeeping_task_assigned_to edge's target; absent while nobody or a worker group holds it", "type": "string" }, "block_reason": { "enum": [ "do_not_disturb", "guest_in_room", "access_refused", "maintenance_required", "other" ], "title": "Why the task is blocked (do-not-disturb workflow)", "type": "string" }, "business_date": { "format": "date", "title": "Service date the task belongs to", "type": "string" }, "completed_at": { "format": "date-time", "title": "Completed at", "type": "string" }, "credits": { "format": "decimal", "title": "Credits the task is worth (zero or more) — stamped at creation from the property's housekeeping credit rule for its task type and room type, or set by hand; absent when the house prices none", "type": "string" }, "due_at": { "format": "date-time", "title": "When the work is due — the guest's 'by three o'clock'; absent when the task has no time of its own. Its urgency (overdue, soon, scheduled) is the housekeeping_requests read's", "type": "string" }, "generation_key": { "title": "Replay key stamped by generate_housekeeping_tasks (hk:{room}:{date}:{type}, or hk:area:{area}:{date} for a public area's daily clean); absent on manually minted tasks", "type": "string" }, "group_id": { "title": "The worker group that holds the task (its object id) — the housekeeping_task_assigned_to_group edge's target; absent while a person or nobody holds it", "type": "string" }, "id": { "title": "Task id", "type": "string" }, "inspection_outcome": { "enum": [ "passed", "failed" ], "title": "passed, or failed (the room went back for a re-clean): on an inspection task, its verdict; on a cleaning task, the verdict of the latest inspection of it", "type": "string" }, "inspection_rating": { "title": "The supervisor's score, 1 (poor) to 5 (excellent): on an inspection task, the score it gave; on a cleaning task, the score the latest inspection of it gave", "type": "integer" }, "notes": { "title": "Notes", "type": "string" }, "origin": { "enum": [ "generated", "manual", "reclean", "from_triage" ], "title": "Where the task came from: generated (the day's board, with a generation_key), manual (create_housekeeping_task), reclean (a failed inspection sent the cleaning back) or from_triage (a triaged guest request). Absent on tasks minted before it was stamped", "type": "string" }, "overdue_at": { "format": "date-time", "title": "When the request_overdue sweep found the due time passed with the work still open — the overdue push went out then; absent until it does, and cleared by a re-time into the future", "type": "string" }, "priority": { "enum": [ "low", "normal", "high", "urgent" ], "title": "Priority", "type": "string" }, "requested_at": { "format": "date-time", "title": "Requested at", "type": "string" }, "requested_by": { "enum": [ "guest", "desk", "floor", "pms", "automation" ], "title": "Who asked for the work: guest, desk, floor, pms (the house's own state — the generator's room board) or automation (a schedule, an agent or a service). Distinct from origin, which says how the task was minted. Absent on tasks minted before it was stamped", "type": "string" }, "room_id": { "title": "The room the task is for (its object id) — the housekeeping_task_for_room edge's target; absent on a public area's task", "type": "string" }, "self_rating": { "title": "The rating the attendant gave their own work at Finish, 1 (poor) to 5 (excellent) — complete tasks only, never an inspection; the supervisor's score is inspection_rating", "type": "integer" }, "skip_reason": { "title": "Why the task was deliberately not done", "type": "string" }, "standard_minutes": { "title": "Minutes the work should take (1 to 1440), stamped beside credits; the pacing report's deviation is measured against it", "type": "integer" }, "started_at": { "format": "date-time", "title": "When the attendant entered the room", "type": "string" }, "status": { "enum": [ "pending", "in_progress", "blocked", "complete", "skipped" ], "title": "Status", "type": "string" }, "task_type": { "enum": [ "stayover", "departure", "vacant_pickup", "deep_clean", "turndown", "inspection", "public_area_clean", "public_area_inspection", "minibar", "laundry" ], "title": "Task type", "type": "string" } }, "required": [ "id", "task_type", "status", "requested_at", "priority" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.housekeeping_task:read" ] } ], "summary": "Read Housekeeping task", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.housekeeping_task/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA unit of housekeeping work attached to a room: a stayover clean, a departure clean, a deep clean, a turndown, an inspection. Minted by `generate_housekeeping_tasks` (which derives the day's board from occupancy + due-outs and stamps a `generation_key` so re-runs converge) or by `create_housekeeping_task` for ad-hoc work (`origin` says which, and marks a failed inspection's re-clean). Assignment is the `housekeeping_task_assigned_to` edge; the per-attendant task sheet is a projection over (assignee, business_date), never a second object to keep in sync. A public area's work (2026-10-14) is the same object linked `housekeeping_task_for_area` instead of to a room — a task is for a room or an area, never both, and the `public_area_*` types are an area's alone; and a task may be assigned to a `worker_group` (`housekeeping_task_assigned_to_group`) instead of a person, until a member starts it. A task is also a request (2026-10-15): `requested_by` says who asked (a guest's request links the stay, `housekeeping_task_requested_by_stay`), `due_at` when it is due, and it carries a thread of notes (`housekeeping_task_entry`). `area_id`, `assignee_id` and `group_id` copy the area, person and group edges onto the row.", "operationId": "get_hospitality_housekeeping_task_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.housekeeping_task:read" ] } ], "summary": "Read Housekeeping task as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.housekeeping_task/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA unit of housekeeping work attached to a room: a stayover clean, a departure clean, a deep clean, a turndown, an inspection. Minted by `generate_housekeeping_tasks` (which derives the day's board from occupancy + due-outs and stamps a `generation_key` so re-runs converge) or by `create_housekeeping_task` for ad-hoc work (`origin` says which, and marks a failed inspection's re-clean). Assignment is the `housekeeping_task_assigned_to` edge; the per-attendant task sheet is a projection over (assignee, business_date), never a second object to keep in sync. A public area's work (2026-10-14) is the same object linked `housekeeping_task_for_area` instead of to a room — a task is for a room or an area, never both, and the `public_area_*` types are an area's alone; and a task may be assigned to a `worker_group` (`housekeeping_task_assigned_to_group`) instead of a person, until a member starts it. A task is also a request (2026-10-15): `requested_by` says who asked (a guest's request links the stay, `housekeeping_task_requested_by_stay`), `due_at` when it is due, and it carries a thread of notes (`housekeeping_task_entry`). `area_id`, `assignee_id` and `group_id` copy the area, person and group edges onto the row.", "operationId": "list_links_hospitality_housekeeping_task", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.housekeeping_task:read" ] } ], "summary": "List links of Housekeeping task", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.checklist_result_for_task", "hospitality.link.housekeeping_task_assigned_to", "hospitality.link.housekeeping_task_assigned_to_group", "hospitality.link.housekeeping_task_entry_for_task", "hospitality.link.housekeeping_task_for_area", "hospitality.link.housekeeping_task_for_room", "hospitality.link.housekeeping_task_from_inspection", "hospitality.link.housekeeping_task_from_triage", "hospitality.link.housekeeping_task_requested_by_stay", "hospitality.link.inspection_rates_task", "hospitality.link.pattern_clusters_housekeeping_task", "hospitality.link.stock_movement_for_housekeeping_task" ] } } ] }, "/v1/object-types/hospitality.housekeeping_task/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA unit of housekeeping work attached to a room: a stayover clean, a departure clean, a deep clean, a turndown, an inspection. Minted by `generate_housekeeping_tasks` (which derives the day's board from occupancy + due-outs and stamps a `generation_key` so re-runs converge) or by `create_housekeeping_task` for ad-hoc work (`origin` says which, and marks a failed inspection's re-clean). Assignment is the `housekeeping_task_assigned_to` edge; the per-attendant task sheet is a projection over (assignee, business_date), never a second object to keep in sync. A public area's work (2026-10-14) is the same object linked `housekeeping_task_for_area` instead of to a room — a task is for a room or an area, never both, and the `public_area_*` types are an area's alone; and a task may be assigned to a `worker_group` (`housekeeping_task_assigned_to_group`) instead of a person, until a member starts it. A task is also a request (2026-10-15): `requested_by` says who asked (a guest's request links the stay, `housekeeping_task_requested_by_stay`), `due_at` when it is due, and it carries a thread of notes (`housekeeping_task_entry`). `area_id`, `assignee_id` and `group_id` copy the area, person and group edges onto the row.", "operationId": "traverse_hospitality_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.checklist_result_for_task", "hospitality.link.housekeeping_task_assigned_to", "hospitality.link.housekeeping_task_assigned_to_group", "hospitality.link.housekeeping_task_entry_for_task", "hospitality.link.housekeeping_task_for_area", "hospitality.link.housekeeping_task_for_room", "hospitality.link.housekeeping_task_from_inspection", "hospitality.link.housekeeping_task_from_triage", "hospitality.link.housekeeping_task_requested_by_stay", "hospitality.link.inspection_rates_task", "hospitality.link.pattern_clusters_housekeeping_task", "hospitality.link.stock_movement_for_housekeeping_task" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.housekeeping_task:read" ] } ], "summary": "Traverse from Housekeeping task", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.housekeeping_task/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA unit of housekeeping work attached to a room: a stayover clean, a departure clean, a deep clean, a turndown, an inspection. Minted by `generate_housekeeping_tasks` (which derives the day's board from occupancy + due-outs and stamps a `generation_key` so re-runs converge) or by `create_housekeeping_task` for ad-hoc work (`origin` says which, and marks a failed inspection's re-clean). Assignment is the `housekeeping_task_assigned_to` edge; the per-attendant task sheet is a projection over (assignee, business_date), never a second object to keep in sync. A public area's work (2026-10-14) is the same object linked `housekeeping_task_for_area` instead of to a room — a task is for a room or an area, never both, and the `public_area_*` types are an area's alone; and a task may be assigned to a `worker_group` (`housekeeping_task_assigned_to_group`) instead of a person, until a member starts it. A task is also a request (2026-10-15): `requested_by` says who asked (a guest's request links the stay, `housekeeping_task_requested_by_stay`), `due_at` when it is due, and it carries a thread of notes (`housekeeping_task_entry`). `area_id`, `assignee_id` and `group_id` copy the area, person and group edges onto the row.", "operationId": "search_hospitality_housekeeping_task", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "task_type" }, "type": { "const": "eq" }, "value": { "enum": [ "stayover", "departure", "vacant_pickup", "deep_clean", "turndown", "inspection", "public_area_clean", "public_area_inspection", "minibar", "laundry" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "pending", "in_progress", "blocked", "complete", "skipped" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "generation_key" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "generation_key" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "generation_key" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "generation_key" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "block_reason" }, "type": { "const": "eq" }, "value": { "enum": [ "do_not_disturb", "guest_in_room", "access_refused", "maintenance_required", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "skip_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "skip_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "priority" }, "type": { "const": "eq" }, "value": { "enum": [ "low", "normal", "high", "urgent" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "credits" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "credits" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "credits" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "standard_minutes" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "standard_minutes" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "standard_minutes" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "inspection_rating" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "inspection_rating" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "inspection_rating" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "inspection_outcome" }, "type": { "const": "eq" }, "value": { "enum": [ "passed", "failed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "origin" }, "type": { "const": "eq" }, "value": { "enum": [ "generated", "manual", "reclean", "from_triage" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "self_rating" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "self_rating" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "self_rating" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_by" }, "type": { "const": "eq" }, "value": { "enum": [ "guest", "desk", "floor", "pms", "automation" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "due_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "due_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "due_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "area_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "area_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "area_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "area_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "room_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "room_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "room_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "room_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "overdue_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "overdue_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "overdue_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "assignee_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "assignee_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "assignee_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "assignee_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "group_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "group_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "group_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "group_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "task_type", "status", "requested_at", "business_date", "generation_key", "started_at", "completed_at", "block_reason", "skip_reason", "notes", "priority", "credits", "standard_minutes", "inspection_rating", "inspection_outcome", "origin", "self_rating", "requested_by", "due_at", "area_id", "room_id", "overdue_at", "assignee_id", "group_id" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task" }, "properties": { "additionalProperties": false, "properties": { "area_id": { "title": "The public area the task is for (its object id) — the housekeeping_task_for_area edge's target; absent on a room's task", "type": "string" }, "assignee_id": { "title": "The staff member who holds the task (their object id) — the housekeeping_task_assigned_to edge's target; absent while nobody or a worker group holds it", "type": "string" }, "block_reason": { "enum": [ "do_not_disturb", "guest_in_room", "access_refused", "maintenance_required", "other" ], "title": "Why the task is blocked (do-not-disturb workflow)", "type": "string" }, "business_date": { "format": "date", "title": "Service date the task belongs to", "type": "string" }, "completed_at": { "format": "date-time", "title": "Completed at", "type": "string" }, "credits": { "format": "decimal", "title": "Credits the task is worth (zero or more) — stamped at creation from the property's housekeeping credit rule for its task type and room type, or set by hand; absent when the house prices none", "type": "string" }, "due_at": { "format": "date-time", "title": "When the work is due — the guest's 'by three o'clock'; absent when the task has no time of its own. Its urgency (overdue, soon, scheduled) is the housekeeping_requests read's", "type": "string" }, "generation_key": { "title": "Replay key stamped by generate_housekeeping_tasks (hk:{room}:{date}:{type}, or hk:area:{area}:{date} for a public area's daily clean); absent on manually minted tasks", "type": "string" }, "group_id": { "title": "The worker group that holds the task (its object id) — the housekeeping_task_assigned_to_group edge's target; absent while a person or nobody holds it", "type": "string" }, "id": { "title": "Task id", "type": "string" }, "inspection_outcome": { "enum": [ "passed", "failed" ], "title": "passed, or failed (the room went back for a re-clean): on an inspection task, its verdict; on a cleaning task, the verdict of the latest inspection of it", "type": "string" }, "inspection_rating": { "title": "The supervisor's score, 1 (poor) to 5 (excellent): on an inspection task, the score it gave; on a cleaning task, the score the latest inspection of it gave", "type": "integer" }, "notes": { "title": "Notes", "type": "string" }, "origin": { "enum": [ "generated", "manual", "reclean", "from_triage" ], "title": "Where the task came from: generated (the day's board, with a generation_key), manual (create_housekeeping_task), reclean (a failed inspection sent the cleaning back) or from_triage (a triaged guest request). Absent on tasks minted before it was stamped", "type": "string" }, "overdue_at": { "format": "date-time", "title": "When the request_overdue sweep found the due time passed with the work still open — the overdue push went out then; absent until it does, and cleared by a re-time into the future", "type": "string" }, "priority": { "enum": [ "low", "normal", "high", "urgent" ], "title": "Priority", "type": "string" }, "requested_at": { "format": "date-time", "title": "Requested at", "type": "string" }, "requested_by": { "enum": [ "guest", "desk", "floor", "pms", "automation" ], "title": "Who asked for the work: guest, desk, floor, pms (the house's own state — the generator's room board) or automation (a schedule, an agent or a service). Distinct from origin, which says how the task was minted. Absent on tasks minted before it was stamped", "type": "string" }, "room_id": { "title": "The room the task is for (its object id) — the housekeeping_task_for_room edge's target; absent on a public area's task", "type": "string" }, "self_rating": { "title": "The rating the attendant gave their own work at Finish, 1 (poor) to 5 (excellent) — complete tasks only, never an inspection; the supervisor's score is inspection_rating", "type": "integer" }, "skip_reason": { "title": "Why the task was deliberately not done", "type": "string" }, "standard_minutes": { "title": "Minutes the work should take (1 to 1440), stamped beside credits; the pacing report's deviation is measured against it", "type": "integer" }, "started_at": { "format": "date-time", "title": "When the attendant entered the room", "type": "string" }, "status": { "enum": [ "pending", "in_progress", "blocked", "complete", "skipped" ], "title": "Status", "type": "string" }, "task_type": { "enum": [ "stayover", "departure", "vacant_pickup", "deep_clean", "turndown", "inspection", "public_area_clean", "public_area_inspection", "minibar", "laundry" ], "title": "Task type", "type": "string" } }, "required": [ "id", "task_type", "status", "requested_at", "priority" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.housekeeping_task:read" ] } ], "summary": "Search Housekeeping task", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.housekeeping_task_entry/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne line on a housekeeping task's thread — what the attendant, the runner or the supervisor says about this piece of work (\"guest asked for feather-free pillows\", \"stain on the carpet by the window\"), as opposed to the day's briefing to the whole floor. A `note` with its words; a photo hangs off the line as an attachment (`host_kind = housekeeping_task_entry`). Linked to its task (`housekeeping_task_entry_for_task`) and to the staff member who wrote it when one did (`housekeeping_task_entry_recorded_by`); `recorded_by` names the principal either way, and `recorded_at` is the handset's own time when it queued the line offline. Written by `record_housekeeping_task_entry`; append-only — a correction is another line.", "operationId": "get_hospitality_housekeeping_task_entry", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task_entry" }, "properties": { "additionalProperties": false, "properties": { "id": { "title": "Housekeeping task entry id", "type": "string" }, "kind": { "enum": [ "note" ], "title": "What the line records: a note", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When the line was written — the handset's own time when it queued offline", "type": "string" }, "recorded_by": { "title": "The principal that wrote the line (`user:…`, `agent:…`, `service:…`, `system`)", "type": "string" }, "text": { "title": "The words on the line (required for a note)", "type": "string" } }, "required": [ "id", "kind", "recorded_at", "recorded_by" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.housekeeping_task_entry:read" ] } ], "summary": "Read Housekeeping task entry", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.housekeeping_task_entry/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne line on a housekeeping task's thread — what the attendant, the runner or the supervisor says about this piece of work (\"guest asked for feather-free pillows\", \"stain on the carpet by the window\"), as opposed to the day's briefing to the whole floor. A `note` with its words; a photo hangs off the line as an attachment (`host_kind = housekeeping_task_entry`). Linked to its task (`housekeeping_task_entry_for_task`) and to the staff member who wrote it when one did (`housekeeping_task_entry_recorded_by`); `recorded_by` names the principal either way, and `recorded_at` is the handset's own time when it queued the line offline. Written by `record_housekeeping_task_entry`; append-only — a correction is another line.", "operationId": "get_hospitality_housekeeping_task_entry_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task_entry" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.housekeeping_task_entry:read" ] } ], "summary": "Read Housekeeping task entry as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.housekeeping_task_entry/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne line on a housekeeping task's thread — what the attendant, the runner or the supervisor says about this piece of work (\"guest asked for feather-free pillows\", \"stain on the carpet by the window\"), as opposed to the day's briefing to the whole floor. A `note` with its words; a photo hangs off the line as an attachment (`host_kind = housekeeping_task_entry`). Linked to its task (`housekeeping_task_entry_for_task`) and to the staff member who wrote it when one did (`housekeeping_task_entry_recorded_by`); `recorded_by` names the principal either way, and `recorded_at` is the handset's own time when it queued the line offline. Written by `record_housekeeping_task_entry`; append-only — a correction is another line.", "operationId": "list_links_hospitality_housekeeping_task_entry", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.housekeeping_task_entry:read" ] } ], "summary": "List links of Housekeeping task entry", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.housekeeping_task_entry_for_task", "hospitality.link.housekeeping_task_entry_recorded_by", "hospitality.link.stored_object_for_housekeeping_task_entry" ] } } ] }, "/v1/object-types/hospitality.housekeeping_task_entry/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne line on a housekeeping task's thread — what the attendant, the runner or the supervisor says about this piece of work (\"guest asked for feather-free pillows\", \"stain on the carpet by the window\"), as opposed to the day's briefing to the whole floor. A `note` with its words; a photo hangs off the line as an attachment (`host_kind = housekeeping_task_entry`). Linked to its task (`housekeeping_task_entry_for_task`) and to the staff member who wrote it when one did (`housekeeping_task_entry_recorded_by`); `recorded_by` names the principal either way, and `recorded_at` is the handset's own time when it queued the line offline. Written by `record_housekeeping_task_entry`; append-only — a correction is another line.", "operationId": "traverse_hospitality_housekeeping_task_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.housekeeping_task_entry_for_task", "hospitality.link.housekeeping_task_entry_recorded_by", "hospitality.link.stored_object_for_housekeeping_task_entry" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.housekeeping_task_entry:read" ] } ], "summary": "Traverse from Housekeeping task entry", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.housekeeping_task_entry/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne line on a housekeeping task's thread — what the attendant, the runner or the supervisor says about this piece of work (\"guest asked for feather-free pillows\", \"stain on the carpet by the window\"), as opposed to the day's briefing to the whole floor. A `note` with its words; a photo hangs off the line as an attachment (`host_kind = housekeeping_task_entry`). Linked to its task (`housekeeping_task_entry_for_task`) and to the staff member who wrote it when one did (`housekeeping_task_entry_recorded_by`); `recorded_by` names the principal either way, and `recorded_at` is the handset's own time when it queued the line offline. Written by `record_housekeeping_task_entry`; append-only — a correction is another line.", "operationId": "search_hospitality_housekeeping_task_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "note" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "kind", "text", "recorded_at", "recorded_by" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.housekeeping_task_entry" }, "properties": { "additionalProperties": false, "properties": { "id": { "title": "Housekeeping task entry id", "type": "string" }, "kind": { "enum": [ "note" ], "title": "What the line records: a note", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When the line was written — the handset's own time when it queued offline", "type": "string" }, "recorded_by": { "title": "The principal that wrote the line (`user:…`, `agent:…`, `service:…`, `system`)", "type": "string" }, "text": { "title": "The words on the line (required for a note)", "type": "string" } }, "required": [ "id", "kind", "recorded_at", "recorded_by" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.housekeeping_task_entry:read" ] } ], "summary": "Search Housekeeping task entry", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.incidental_hold_policy/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne property's rule for the card hold a check-in suggests: a basis (the allowance per night, the room total plus the allowance per night, the room total plus a flat amount, or a flat amount — OPERA's authorization rules 7, 2, 9 and 5), the allowance, and optionally the reservation guarantee it is for (a prepaid stay holds incidentals only, a card-guaranteed one the room as well). Rules are keyed by `code` within the property; `suggest_incidental_hold` picks the active rule for the reservation's guarantee, falling back to the rule for any guarantee. Since 2026-10-19 a rule may also name a room type, a rate plan and a booking source (OPERA's advanced rules, most specific first), four more of OPERA's formulas (the room alone, per person, a percentage of the room), and the night audit's top-up takes the rule's allowance as what the card must still cover beyond the bill.", "operationId": "get_hospitality_incidental_hold_policy", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.incidental_hold_policy" }, "properties": { "additionalProperties": false, "properties": { "active": { "title": "Whether check-ins draw on this rule", "type": "boolean" }, "allowance": { "description": "The per-night allowance (`per_night`, `room_and_per_night`) or the flat amount (`room_plus_flat`, `flat`)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Incidental hold policy allowance", "type": "object" }, "basis": { "enum": [ "per_night", "room_and_per_night", "room_plus_flat", "flat", "room", "room_and_per_person_night", "per_person_night", "room_plus_percent" ], "title": "How the suggested hold computes", "type": "string" }, "code": { "title": "Policy code — the rule's identity within the property", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "guarantee": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "title": "The reservation guarantee this rule is for; absent = any guarantee without a rule of its own", "type": "string" }, "id": { "title": "Incidental hold policy id", "type": "string" }, "percent": { "format": "decimal", "title": "The percentage of the room total `room_plus_percent` adds (10 = 10%)", "type": "string" }, "rate_plan_ref": { "format": "uuid", "title": "The rate plan this rule is for; absent = any rate plan", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_ref": { "format": "uuid", "title": "The room type this rule is for; absent = any room type", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "The booking source this rule is for; absent = any source", "type": "string" } }, "required": [ "id", "code", "basis", "allowance", "active" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.incidental_hold_policy:read" ] } ], "summary": "Read Incidental hold policy", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.incidental_hold_policy/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne property's rule for the card hold a check-in suggests: a basis (the allowance per night, the room total plus the allowance per night, the room total plus a flat amount, or a flat amount — OPERA's authorization rules 7, 2, 9 and 5), the allowance, and optionally the reservation guarantee it is for (a prepaid stay holds incidentals only, a card-guaranteed one the room as well). Rules are keyed by `code` within the property; `suggest_incidental_hold` picks the active rule for the reservation's guarantee, falling back to the rule for any guarantee. Since 2026-10-19 a rule may also name a room type, a rate plan and a booking source (OPERA's advanced rules, most specific first), four more of OPERA's formulas (the room alone, per person, a percentage of the room), and the night audit's top-up takes the rule's allowance as what the card must still cover beyond the bill.", "operationId": "get_hospitality_incidental_hold_policy_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.incidental_hold_policy" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.incidental_hold_policy:read" ] } ], "summary": "Read Incidental hold policy as of a watermark", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.incidental_hold_policy/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne property's rule for the card hold a check-in suggests: a basis (the allowance per night, the room total plus the allowance per night, the room total plus a flat amount, or a flat amount — OPERA's authorization rules 7, 2, 9 and 5), the allowance, and optionally the reservation guarantee it is for (a prepaid stay holds incidentals only, a card-guaranteed one the room as well). Rules are keyed by `code` within the property; `suggest_incidental_hold` picks the active rule for the reservation's guarantee, falling back to the rule for any guarantee. Since 2026-10-19 a rule may also name a room type, a rate plan and a booking source (OPERA's advanced rules, most specific first), four more of OPERA's formulas (the room alone, per person, a percentage of the room), and the night audit's top-up takes the rule's allowance as what the card must still cover beyond the bill.", "operationId": "list_links_hospitality_incidental_hold_policy", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.incidental_hold_policy:read" ] } ], "summary": "List links of Incidental hold policy", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.incidental_hold_policy_at_property" ] } } ] }, "/v1/object-types/hospitality.incidental_hold_policy/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne property's rule for the card hold a check-in suggests: a basis (the allowance per night, the room total plus the allowance per night, the room total plus a flat amount, or a flat amount — OPERA's authorization rules 7, 2, 9 and 5), the allowance, and optionally the reservation guarantee it is for (a prepaid stay holds incidentals only, a card-guaranteed one the room as well). Rules are keyed by `code` within the property; `suggest_incidental_hold` picks the active rule for the reservation's guarantee, falling back to the rule for any guarantee. Since 2026-10-19 a rule may also name a room type, a rate plan and a booking source (OPERA's advanced rules, most specific first), four more of OPERA's formulas (the room alone, per person, a percentage of the room), and the night audit's top-up takes the rule's allowance as what the card must still cover beyond the bill.", "operationId": "traverse_hospitality_incidental_hold_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.incidental_hold_policy_at_property" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.incidental_hold_policy:read" ] } ], "summary": "Traverse from Incidental hold policy", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.incidental_hold_policy/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne property's rule for the card hold a check-in suggests: a basis (the allowance per night, the room total plus the allowance per night, the room total plus a flat amount, or a flat amount — OPERA's authorization rules 7, 2, 9 and 5), the allowance, and optionally the reservation guarantee it is for (a prepaid stay holds incidentals only, a card-guaranteed one the room as well). Rules are keyed by `code` within the property; `suggest_incidental_hold` picks the active rule for the reservation's guarantee, falling back to the rule for any guarantee. Since 2026-10-19 a rule may also name a room type, a rate plan and a booking source (OPERA's advanced rules, most specific first), four more of OPERA's formulas (the room alone, per person, a percentage of the room), and the night audit's top-up takes the rule's allowance as what the card must still cover beyond the bill.", "operationId": "search_hospitality_incidental_hold_policy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "guarantee" }, "type": { "const": "eq" }, "value": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "basis" }, "type": { "const": "eq" }, "value": { "enum": [ "per_night", "room_and_per_night", "room_plus_flat", "flat", "room", "room_and_per_person_night", "per_person_night", "room_plus_percent" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "allowance" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "active" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "room_type_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.room_type" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rate_plan_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.rate_plan" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source" }, "type": { "const": "eq" }, "value": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "percent" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "percent" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "percent" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "code", "guarantee", "basis", "description", "source", "percent" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.incidental_hold_policy" }, "properties": { "additionalProperties": false, "properties": { "active": { "title": "Whether check-ins draw on this rule", "type": "boolean" }, "allowance": { "description": "The per-night allowance (`per_night`, `room_and_per_night`) or the flat amount (`room_plus_flat`, `flat`)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Incidental hold policy allowance", "type": "object" }, "basis": { "enum": [ "per_night", "room_and_per_night", "room_plus_flat", "flat", "room", "room_and_per_person_night", "per_person_night", "room_plus_percent" ], "title": "How the suggested hold computes", "type": "string" }, "code": { "title": "Policy code — the rule's identity within the property", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "guarantee": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "title": "The reservation guarantee this rule is for; absent = any guarantee without a rule of its own", "type": "string" }, "id": { "title": "Incidental hold policy id", "type": "string" }, "percent": { "format": "decimal", "title": "The percentage of the room total `room_plus_percent` adds (10 = 10%)", "type": "string" }, "rate_plan_ref": { "format": "uuid", "title": "The rate plan this rule is for; absent = any rate plan", "type": "string", "x-aerandil-references": "hospitality.rate_plan" }, "room_type_ref": { "format": "uuid", "title": "The room type this rule is for; absent = any room type", "type": "string", "x-aerandil-references": "hospitality.room_type" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "The booking source this rule is for; absent = any source", "type": "string" } }, "required": [ "id", "code", "basis", "allowance", "active" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.incidental_hold_policy:read" ] } ], "summary": "Search Incidental hold policy", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.ingredient/objects/{id}": { "get": { "description": "Read an existing instance.\n\nF&B ingredient catalog row (identity + canonical unit + allergen disclosure). Supplier price is property-scoped via the `ingredient_supplier_price` companion per design- spec §B.3; the `refresh_recipe_pour_cost` flow reads the active price row for the recipe's property. Source-side allergen flags roll up into `recipe.allergens`.", "operationId": "get_hospitality_ingredient", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.ingredient" }, "properties": { "additionalProperties": false, "properties": { "allergen_flags": { "items": { "enum": [ "gluten", "crustaceans", "eggs", "fish", "peanuts", "soybeans", "milk", "nuts", "celery", "mustard", "sesame", "sulphites", "lupin", "molluscs" ], "type": "string" }, "title": "Allergen flags (EU 14 list)", "type": "array" }, "category": { "enum": [ "spirit", "wine", "beer", "liqueur", "bitters", "syrup", "juice", "garnish_fruit", "garnish_herb", "dairy", "protein", "produce", "dry_good", "spice", "other" ], "title": "Category", "type": "string" }, "code": { "title": "Ingredient code", "type": "string" }, "id": { "title": "Ingredient id", "type": "string" }, "name": { "title": "Ingredient name", "type": "string" }, "par_quantity": { "format": "decimal", "title": "Par stock level", "type": "string" }, "unit_canonical": { "enum": [ "ml", "cl", "oz", "g", "kg", "each", "dash", "drop", "rim", "float", "scoop", "other" ], "title": "Canonical unit", "type": "string" } }, "required": [ "id", "code", "name", "category", "unit_canonical" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.ingredient:read" ] } ], "summary": "Read Ingredient", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.ingredient/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nF&B ingredient catalog row (identity + canonical unit + allergen disclosure). Supplier price is property-scoped via the `ingredient_supplier_price` companion per design- spec §B.3; the `refresh_recipe_pour_cost` flow reads the active price row for the recipe's property. Source-side allergen flags roll up into `recipe.allergens`.", "operationId": "get_hospitality_ingredient_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.ingredient" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.ingredient:read" ] } ], "summary": "Read Ingredient as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.ingredient/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nF&B ingredient catalog row (identity + canonical unit + allergen disclosure). Supplier price is property-scoped via the `ingredient_supplier_price` companion per design- spec §B.3; the `refresh_recipe_pour_cost` flow reads the active price row for the recipe's property. Source-side allergen flags roll up into `recipe.allergens`.", "operationId": "list_links_hospitality_ingredient", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.ingredient:read" ] } ], "summary": "List links of Ingredient", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.ingredient_at_brand", "hospitality.link.ingredient_at_property", "hospitality.link.ingredient_supplier_price_for_ingredient", "hospitality.link.recipe_uses_ingredient" ] } } ] }, "/v1/object-types/hospitality.ingredient/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nF&B ingredient catalog row (identity + canonical unit + allergen disclosure). Supplier price is property-scoped via the `ingredient_supplier_price` companion per design- spec §B.3; the `refresh_recipe_pour_cost` flow reads the active price row for the recipe's property. Source-side allergen flags roll up into `recipe.allergens`.", "operationId": "traverse_hospitality_ingredient", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.ingredient_at_brand", "hospitality.link.ingredient_at_property", "hospitality.link.ingredient_supplier_price_for_ingredient", "hospitality.link.recipe_uses_ingredient" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.ingredient:read" ] } ], "summary": "Traverse from Ingredient", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.ingredient/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nF&B ingredient catalog row (identity + canonical unit + allergen disclosure). Supplier price is property-scoped via the `ingredient_supplier_price` companion per design- spec §B.3; the `refresh_recipe_pour_cost` flow reads the active price row for the recipe's property. Source-side allergen flags roll up into `recipe.allergens`.", "operationId": "search_hospitality_ingredient", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "category" }, "type": { "const": "eq" }, "value": { "enum": [ "spirit", "wine", "beer", "liqueur", "bitters", "syrup", "juice", "garnish_fruit", "garnish_herb", "dairy", "protein", "produce", "dry_good", "spice", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "unit_canonical" }, "type": { "const": "eq" }, "value": { "enum": [ "ml", "cl", "oz", "g", "kg", "each", "dash", "drop", "rim", "float", "scoop", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "par_quantity" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "par_quantity" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "par_quantity" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "allergen_flags" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "gluten", "crustaceans", "eggs", "fish", "peanuts", "soybeans", "milk", "nuts", "celery", "mustard", "sesame", "sulphites", "lupin", "molluscs" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "code", "name", "category", "unit_canonical", "par_quantity" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.ingredient" }, "properties": { "additionalProperties": false, "properties": { "allergen_flags": { "items": { "enum": [ "gluten", "crustaceans", "eggs", "fish", "peanuts", "soybeans", "milk", "nuts", "celery", "mustard", "sesame", "sulphites", "lupin", "molluscs" ], "type": "string" }, "title": "Allergen flags (EU 14 list)", "type": "array" }, "category": { "enum": [ "spirit", "wine", "beer", "liqueur", "bitters", "syrup", "juice", "garnish_fruit", "garnish_herb", "dairy", "protein", "produce", "dry_good", "spice", "other" ], "title": "Category", "type": "string" }, "code": { "title": "Ingredient code", "type": "string" }, "id": { "title": "Ingredient id", "type": "string" }, "name": { "title": "Ingredient name", "type": "string" }, "par_quantity": { "format": "decimal", "title": "Par stock level", "type": "string" }, "unit_canonical": { "enum": [ "ml", "cl", "oz", "g", "kg", "each", "dash", "drop", "rim", "float", "scoop", "other" ], "title": "Canonical unit", "type": "string" } }, "required": [ "id", "code", "name", "category", "unit_canonical" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.ingredient:read" ] } ], "summary": "Search Ingredient", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.ingredient_supplier_price/objects/{id}": { "get": { "description": "Read an existing instance.\n\nPer-property supplier price for an ingredient. The pour-cost rollup reads the active row (`effective_to IS NULL`) for the recipe's property. Append-only ledger via `effective_from` / `effective_to` — supplier invoices land as fresh rows; the handler closes the prior open row.", "operationId": "get_hospitality_ingredient_supplier_price", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.ingredient_supplier_price" }, "properties": { "additionalProperties": false, "properties": { "cost_per_unit_canonical": { "description": "Cost per canonical unit", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Ingredient supplier price cost per unit canonical", "type": "object" }, "effective_from": { "format": "date-time", "title": "Effective from", "type": "string" }, "effective_to": { "format": "date-time", "title": "Effective to (null = currently in effect)", "type": "string" }, "id": { "title": "Price id", "type": "string" }, "ingredient_ref": { "format": "uuid", "title": "Ingredient", "type": "string", "x-aerandil-references": "hospitality.ingredient" }, "invoice_reference": { "title": "Supplier invoice reference", "type": "string" }, "property_ref": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "received_at": { "format": "date-time", "title": "Received at (supplier invoice timestamp)", "type": "string" }, "supplier_code": { "title": "Supplier code", "type": "string" }, "unit_canonical_at_record": { "enum": [ "ml", "cl", "oz", "g", "kg", "each", "dash", "drop", "rim", "float", "scoop", "other" ], "title": "Canonical unit (snapshot at record time)", "type": "string" } }, "required": [ "id", "ingredient_ref", "property_ref", "unit_canonical_at_record", "received_at", "effective_from" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.ingredient_supplier_price:read" ] } ], "summary": "Read Ingredient supplier price", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.ingredient_supplier_price/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nPer-property supplier price for an ingredient. The pour-cost rollup reads the active row (`effective_to IS NULL`) for the recipe's property. Append-only ledger via `effective_from` / `effective_to` — supplier invoices land as fresh rows; the handler closes the prior open row.", "operationId": "get_hospitality_ingredient_supplier_price_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.ingredient_supplier_price" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.ingredient_supplier_price:read" ] } ], "summary": "Read Ingredient supplier price as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.ingredient_supplier_price/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nPer-property supplier price for an ingredient. The pour-cost rollup reads the active row (`effective_to IS NULL`) for the recipe's property. Append-only ledger via `effective_from` / `effective_to` — supplier invoices land as fresh rows; the handler closes the prior open row.", "operationId": "list_links_hospitality_ingredient_supplier_price", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.ingredient_supplier_price:read" ] } ], "summary": "List links of Ingredient supplier price", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.ingredient_supplier_price_at_property", "hospitality.link.ingredient_supplier_price_for_ingredient" ] } } ] }, "/v1/object-types/hospitality.ingredient_supplier_price/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nPer-property supplier price for an ingredient. The pour-cost rollup reads the active row (`effective_to IS NULL`) for the recipe's property. Append-only ledger via `effective_from` / `effective_to` — supplier invoices land as fresh rows; the handler closes the prior open row.", "operationId": "traverse_hospitality_ingredient_supplier_price", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.ingredient_supplier_price_at_property", "hospitality.link.ingredient_supplier_price_for_ingredient" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.ingredient_supplier_price:read" ] } ], "summary": "Traverse from Ingredient supplier price", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.ingredient_supplier_price/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nPer-property supplier price for an ingredient. The pour-cost rollup reads the active row (`effective_to IS NULL`) for the recipe's property. Append-only ledger via `effective_from` / `effective_to` — supplier invoices land as fresh rows; the handler closes the prior open row.", "operationId": "search_hospitality_ingredient_supplier_price", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ingredient_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.ingredient" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "property_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cost_per_unit_canonical" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "unit_canonical_at_record" }, "type": { "const": "eq" }, "value": { "enum": [ "ml", "cl", "oz", "g", "kg", "each", "dash", "drop", "rim", "float", "scoop", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "supplier_code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "supplier_code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "supplier_code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "supplier_code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "invoice_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "invoice_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "invoice_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "invoice_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "received_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "received_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "received_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "unit_canonical_at_record", "supplier_code", "invoice_reference", "received_at", "effective_from", "effective_to" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.ingredient_supplier_price" }, "properties": { "additionalProperties": false, "properties": { "cost_per_unit_canonical": { "description": "Cost per canonical unit", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Ingredient supplier price cost per unit canonical", "type": "object" }, "effective_from": { "format": "date-time", "title": "Effective from", "type": "string" }, "effective_to": { "format": "date-time", "title": "Effective to (null = currently in effect)", "type": "string" }, "id": { "title": "Price id", "type": "string" }, "ingredient_ref": { "format": "uuid", "title": "Ingredient", "type": "string", "x-aerandil-references": "hospitality.ingredient" }, "invoice_reference": { "title": "Supplier invoice reference", "type": "string" }, "property_ref": { "format": "uuid", "title": "Property", "type": "string", "x-aerandil-references": "hospitality.property" }, "received_at": { "format": "date-time", "title": "Received at (supplier invoice timestamp)", "type": "string" }, "supplier_code": { "title": "Supplier code", "type": "string" }, "unit_canonical_at_record": { "enum": [ "ml", "cl", "oz", "g", "kg", "each", "dash", "drop", "rim", "float", "scoop", "other" ], "title": "Canonical unit (snapshot at record time)", "type": "string" } }, "required": [ "id", "ingredient_ref", "property_ref", "unit_canonical_at_record", "received_at", "effective_from" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.ingredient_supplier_price:read" ] } ], "summary": "Search Ingredient supplier price", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.inspection_round/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne executed walk of a round template (`inspection_round_from_template`) — hubOS's revision. Carries the template's name and family, the due date it answers (`due_on`) and the template's `checkpoints` as they stood when it started, so a revision of the template never changes a walk under way and the record shows the list it was walked against (`template_revision`, the template's revision it copied). Started by hand or by the automation lane when the template falls due (`started_by` names the principal; `inspection_round_started_by` the staff member when one did); each checkpoint is recorded as a `checkpoint_result` (`checkpoint_result_in_round`); `checkpoints_recorded`, `total_anomalies` and `total_faults` are the fold of those results, kept by the verbs. `open` → `completed` (every checkpoint recorded, or `partial` with a reason; moves the template's next due date on) or `cancelled` (with a reason; the occurrence is still owed). Faults raised from it are work orders (`work_order_from_round`).", "operationId": "get_hospitality_inspection_round", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.inspection_round" }, "properties": { "additionalProperties": false, "properties": { "cancel_reason": { "title": "Why the round was cancelled", "type": "string" }, "cancelled_at": { "format": "date-time", "title": "When the round was cancelled", "type": "string" }, "checkpoints": { "description": "The template's checkpoints as they stood when the round started", "items": { "properties": { "items": { "items": { "properties": { "code": { "type": "string" }, "kind": { "enum": [ "check", "reading", "text", "photo", "section" ], "type": "string" }, "label": { "type": "string" }, "max": { "format": "decimal", "type": "string" }, "min": { "format": "decimal", "type": "string" }, "unit": { "type": "string" } }, "required": [ "code", "label", "kind" ], "type": "object" }, "type": "array" }, "kind": { "enum": [ "room", "asset", "general" ], "type": "string" }, "label": { "type": "string" }, "position": { "type": "integer" }, "ref_id": { "type": "string" } }, "required": [ "position", "kind", "items" ], "type": "object" }, "title": "Inspection round checkpoints", "type": "array" }, "checkpoints_recorded": { "title": "How many of its checkpoints have a result", "type": "integer" }, "completed_at": { "format": "date-time", "title": "When the round was finished", "type": "string" }, "completed_by": { "title": "The principal that finished it", "type": "string" }, "due_on": { "format": "date", "title": "The due date this round answers — the template's next_due_on when it started", "type": "string" }, "family": { "enum": [ "corrective", "preventive", "technical_legal", "inspection_legal" ], "title": "The template's family when the round started", "type": "string" }, "id": { "title": "Inspection round id", "type": "string" }, "name": { "title": "The template's name when the round started", "type": "string" }, "observations": { "title": "The walker's observations on the round as a whole", "type": "string" }, "partial": { "title": "Finished with checkpoints unrecorded (with partial_reason)", "type": "boolean" }, "partial_reason": { "title": "Why checkpoints were left unrecorded", "type": "string" }, "started_at": { "format": "date-time", "title": "When the round was started (the handset's own time when it says)", "type": "string" }, "started_by": { "title": "The principal that started it (`user:…`, `agent:…`, `service:…`, `system` — the automation lane when the template fell due)", "type": "string" }, "status": { "enum": [ "open", "completed", "cancelled" ], "title": "open, completed or cancelled", "type": "string" }, "template_revision": { "title": "The template's revision when the round started — the walk the checkpoints were copied from", "type": "integer" }, "total_anomalies": { "title": "Anomalies across its checkpoints (items answered not ok)", "type": "integer" }, "total_faults": { "title": "Work orders raised from its checkpoints", "type": "integer" } }, "required": [ "id", "name", "family", "due_on", "checkpoints", "status", "started_at", "started_by", "checkpoints_recorded", "total_anomalies", "total_faults" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.inspection_round:read" ] } ], "summary": "Read Inspection round", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.inspection_round/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne executed walk of a round template (`inspection_round_from_template`) — hubOS's revision. Carries the template's name and family, the due date it answers (`due_on`) and the template's `checkpoints` as they stood when it started, so a revision of the template never changes a walk under way and the record shows the list it was walked against (`template_revision`, the template's revision it copied). Started by hand or by the automation lane when the template falls due (`started_by` names the principal; `inspection_round_started_by` the staff member when one did); each checkpoint is recorded as a `checkpoint_result` (`checkpoint_result_in_round`); `checkpoints_recorded`, `total_anomalies` and `total_faults` are the fold of those results, kept by the verbs. `open` → `completed` (every checkpoint recorded, or `partial` with a reason; moves the template's next due date on) or `cancelled` (with a reason; the occurrence is still owed). Faults raised from it are work orders (`work_order_from_round`).", "operationId": "get_hospitality_inspection_round_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.inspection_round" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.inspection_round:read" ] } ], "summary": "Read Inspection round as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.inspection_round/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne executed walk of a round template (`inspection_round_from_template`) — hubOS's revision. Carries the template's name and family, the due date it answers (`due_on`) and the template's `checkpoints` as they stood when it started, so a revision of the template never changes a walk under way and the record shows the list it was walked against (`template_revision`, the template's revision it copied). Started by hand or by the automation lane when the template falls due (`started_by` names the principal; `inspection_round_started_by` the staff member when one did); each checkpoint is recorded as a `checkpoint_result` (`checkpoint_result_in_round`); `checkpoints_recorded`, `total_anomalies` and `total_faults` are the fold of those results, kept by the verbs. `open` → `completed` (every checkpoint recorded, or `partial` with a reason; moves the template's next due date on) or `cancelled` (with a reason; the occurrence is still owed). Faults raised from it are work orders (`work_order_from_round`).", "operationId": "list_links_hospitality_inspection_round", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.inspection_round:read" ] } ], "summary": "List links of Inspection round", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.checkpoint_result_in_round", "hospitality.link.inspection_round_completed_by", "hospitality.link.inspection_round_from_template", "hospitality.link.inspection_round_started_by", "hospitality.link.work_order_from_round" ] } } ] }, "/v1/object-types/hospitality.inspection_round/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne executed walk of a round template (`inspection_round_from_template`) — hubOS's revision. Carries the template's name and family, the due date it answers (`due_on`) and the template's `checkpoints` as they stood when it started, so a revision of the template never changes a walk under way and the record shows the list it was walked against (`template_revision`, the template's revision it copied). Started by hand or by the automation lane when the template falls due (`started_by` names the principal; `inspection_round_started_by` the staff member when one did); each checkpoint is recorded as a `checkpoint_result` (`checkpoint_result_in_round`); `checkpoints_recorded`, `total_anomalies` and `total_faults` are the fold of those results, kept by the verbs. `open` → `completed` (every checkpoint recorded, or `partial` with a reason; moves the template's next due date on) or `cancelled` (with a reason; the occurrence is still owed). Faults raised from it are work orders (`work_order_from_round`).", "operationId": "traverse_hospitality_inspection_round", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.checkpoint_result_in_round", "hospitality.link.inspection_round_completed_by", "hospitality.link.inspection_round_from_template", "hospitality.link.inspection_round_started_by", "hospitality.link.work_order_from_round" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.inspection_round:read" ] } ], "summary": "Traverse from Inspection round", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.inspection_round/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne executed walk of a round template (`inspection_round_from_template`) — hubOS's revision. Carries the template's name and family, the due date it answers (`due_on`) and the template's `checkpoints` as they stood when it started, so a revision of the template never changes a walk under way and the record shows the list it was walked against (`template_revision`, the template's revision it copied). Started by hand or by the automation lane when the template falls due (`started_by` names the principal; `inspection_round_started_by` the staff member when one did); each checkpoint is recorded as a `checkpoint_result` (`checkpoint_result_in_round`); `checkpoints_recorded`, `total_anomalies` and `total_faults` are the fold of those results, kept by the verbs. `open` → `completed` (every checkpoint recorded, or `partial` with a reason; moves the template's next due date on) or `cancelled` (with a reason; the occurrence is still owed). Faults raised from it are work orders (`work_order_from_round`).", "operationId": "search_hospitality_inspection_round", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "family" }, "type": { "const": "eq" }, "value": { "enum": [ "corrective", "preventive", "technical_legal", "inspection_legal" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "due_on" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "due_on" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "due_on" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checkpoints" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "items": { "items": { "properties": { "code": { "type": "string" }, "kind": { "enum": [ "check", "reading", "text", "photo", "section" ], "type": "string" }, "label": { "type": "string" }, "max": { "format": "decimal", "type": "string" }, "min": { "format": "decimal", "type": "string" }, "unit": { "type": "string" } }, "required": [ "code", "label", "kind" ], "type": "object" }, "type": "array" }, "kind": { "enum": [ "room", "asset", "general" ], "type": "string" }, "label": { "type": "string" }, "position": { "type": "integer" }, "ref_id": { "type": "string" } }, "required": [ "position", "kind", "items" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "open", "completed", "cancelled" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "partial" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "partial_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "partial_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "observations" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "observations" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancelled_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancelled_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancelled_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancel_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancel_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checkpoints_recorded" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checkpoints_recorded" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checkpoints_recorded" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "total_anomalies" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "total_anomalies" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "total_anomalies" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "total_faults" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "total_faults" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "total_faults" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "template_revision" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "template_revision" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "template_revision" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "name", "family", "due_on", "status", "started_at", "started_by", "completed_at", "completed_by", "partial_reason", "observations", "cancelled_at", "cancel_reason", "checkpoints_recorded", "total_anomalies", "total_faults", "template_revision" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.inspection_round" }, "properties": { "additionalProperties": false, "properties": { "cancel_reason": { "title": "Why the round was cancelled", "type": "string" }, "cancelled_at": { "format": "date-time", "title": "When the round was cancelled", "type": "string" }, "checkpoints": { "description": "The template's checkpoints as they stood when the round started", "items": { "properties": { "items": { "items": { "properties": { "code": { "type": "string" }, "kind": { "enum": [ "check", "reading", "text", "photo", "section" ], "type": "string" }, "label": { "type": "string" }, "max": { "format": "decimal", "type": "string" }, "min": { "format": "decimal", "type": "string" }, "unit": { "type": "string" } }, "required": [ "code", "label", "kind" ], "type": "object" }, "type": "array" }, "kind": { "enum": [ "room", "asset", "general" ], "type": "string" }, "label": { "type": "string" }, "position": { "type": "integer" }, "ref_id": { "type": "string" } }, "required": [ "position", "kind", "items" ], "type": "object" }, "title": "Inspection round checkpoints", "type": "array" }, "checkpoints_recorded": { "title": "How many of its checkpoints have a result", "type": "integer" }, "completed_at": { "format": "date-time", "title": "When the round was finished", "type": "string" }, "completed_by": { "title": "The principal that finished it", "type": "string" }, "due_on": { "format": "date", "title": "The due date this round answers — the template's next_due_on when it started", "type": "string" }, "family": { "enum": [ "corrective", "preventive", "technical_legal", "inspection_legal" ], "title": "The template's family when the round started", "type": "string" }, "id": { "title": "Inspection round id", "type": "string" }, "name": { "title": "The template's name when the round started", "type": "string" }, "observations": { "title": "The walker's observations on the round as a whole", "type": "string" }, "partial": { "title": "Finished with checkpoints unrecorded (with partial_reason)", "type": "boolean" }, "partial_reason": { "title": "Why checkpoints were left unrecorded", "type": "string" }, "started_at": { "format": "date-time", "title": "When the round was started (the handset's own time when it says)", "type": "string" }, "started_by": { "title": "The principal that started it (`user:…`, `agent:…`, `service:…`, `system` — the automation lane when the template fell due)", "type": "string" }, "status": { "enum": [ "open", "completed", "cancelled" ], "title": "open, completed or cancelled", "type": "string" }, "template_revision": { "title": "The template's revision when the round started — the walk the checkpoints were copied from", "type": "integer" }, "total_anomalies": { "title": "Anomalies across its checkpoints (items answered not ok)", "type": "integer" }, "total_faults": { "title": "Work orders raised from its checkpoints", "type": "integer" } }, "required": [ "id", "name", "family", "due_on", "checkpoints", "status", "started_at", "started_by", "checkpoints_recorded", "total_anomalies", "total_faults" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.inspection_round:read" ] } ], "summary": "Search Inspection round", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.invoice/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe numbered, sealed document a folio becomes when it is issued — a tax invoice, or a credit note reversing one. Carries snapshots of the issuer, the recipient, every ledger line and the per-rate tax bands, so the document renders from itself and never changes after issue.", "operationId": "get_hospitality_invoice", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.invoice" }, "properties": { "additionalProperties": false, "properties": { "amount_due": { "description": "Zero on a settled stay; the transferred balance on a folio settled to a company's A/R account.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Invoice amount due", "type": "object" }, "amount_paid": { "description": "Amount paid", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Invoice amount paid", "type": "object" }, "content_hash": { "description": "SHA-256 over the canonical snapshot. With `previous_hash` this chains issued documents, which is what the modern fiscal regimes actually check — they put integrity on a chain over issued records rather than on the integer being dense.", "title": "Content hash", "type": "string" }, "currency": { "format": "iso-4217", "title": "Currency", "type": "string" }, "due_on": { "description": "Only set when `amount_due` is above zero — the company-billed case.", "format": "date", "title": "Payment due", "type": "string" }, "gross_total": { "description": "Gross total", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Invoice gross total", "type": "object" }, "issued_at": { "description": "The instant of issue. Also the renderer's fixed timestamp, which is what makes a re-render byte-identical to the stored PDF.", "format": "date-time", "title": "Issued at", "type": "string" }, "issued_on": { "description": "The property's business date of issue — an action parameter, never `Utc::now()`. This is the document's date for tax purposes.", "format": "date", "title": "Issue date", "type": "string" }, "issuer": { "description": "The property's legal identity, as it printed.", "properties": { "address": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "type": "object" }, "bank_account": { "properties": { "account_name": { "type": "string" }, "account_number": { "type": "string" }, "bic": { "type": "string" }, "iban": { "type": "string" }, "sort_code": { "type": "string" } }, "type": "object" }, "company_registration_number": { "type": "string" }, "contact_email": { "type": "string" }, "contact_phone": { "type": "string" }, "legal_name": { "type": "string" }, "tax_registration_number": { "type": "string" }, "tax_registration_scheme": { "type": "string" } }, "required": [ "legal_name", "address", "tax_registration_scheme" ], "title": "Invoice issuer", "type": "object" }, "kind": { "description": "`invoice`, or `credit_note` reversing one.", "enum": [ "invoice", "credit_note" ], "title": "Document kind", "type": "string" }, "language": { "description": "BCP 47 tag the document was rendered in.", "title": "Language", "type": "string" }, "lines": { "description": "The printed lines, snapshotted at issue.", "items": { "properties": { "bucket": { "type": "string" }, "business_day": { "format": "date", "type": "string" }, "description": { "type": "string" }, "gross": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "net": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "tax": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "business_day", "description", "net", "tax", "gross" ], "type": "object" }, "title": "Invoice lines", "type": "array" }, "net_total": { "description": "Net total", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Invoice net total", "type": "object" }, "note": { "title": "Note", "type": "string" }, "number": { "description": "The legal document number, e.g. `STAN-2026-000123`. Allocated from the property's series inside the issuing transaction and never reissued.", "title": "Invoice number", "type": "string" }, "previous_hash": { "description": "The previous issued document's `content_hash` — one chain per property, spanning invoices AND credit notes together, absent only for the property's first. Deliberately NOT per series: Spain's Orden HAC/1177/2024 art. 7(c) requires a system to produce \"una unica cadena\", and art. 7(d) that the chain carry both the alta and the anulacion records; Basque TicketBAI chains to the previous issued invoice regardless of series. The *number* series stays per kind; the chain is one strand. Backwards here makes Veri-factu a rebuild rather than a configuration.", "title": "Previous content hash", "type": "string" }, "recipient": { "description": "Who the document was addressed to, as it printed.", "properties": { "address": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "type": "object" }, "company_name": { "type": "string" }, "email": { "type": "string" }, "kind": { "type": "string" }, "name": { "type": "string" }, "reference": { "type": "string" }, "tax_identifier": { "type": "string" } }, "required": [ "kind", "name" ], "title": "Invoice recipient", "type": "object" }, "recipient_kind": { "description": "Unmarked twin of `recipient.kind`, so the board can filter company documents without reading the PII snapshot.", "enum": [ "person", "company" ], "title": "Recipient kind", "type": "string" }, "render_version": { "description": "Which renderer produced the stored PDF. A later engine upgrade may change bytes, so a re-render under a different version is a copy, not the original.", "title": "Renderer version", "type": "string" }, "sequence_value": { "description": "The bare counter value `number` was rendered from. Kept so a gap in a series is detectable without parsing the formatted number.", "title": "Sequence value", "type": "integer" }, "series": { "description": "The sequence this number came from — `{property_id}:{kind}:{yyyy}`. Series are annual and per document kind: France requires numbering that is chronological and continuous within a series, and a credit note sharing the invoice run cannot satisfy that.", "title": "Number series", "type": "string" }, "simplified": { "description": "Issued under the small-amount rule (UK £250, DE €250) without recipient details. Never true for a company recipient — the whole point of their document is input-tax recovery.", "title": "Simplified", "type": "boolean" }, "supply_from": { "description": "First day of the period supplied — the stay's arrival. Printed as the Leistungszeitraum.", "format": "date", "title": "Supply from", "type": "string" }, "supply_to": { "description": "Last day of the period supplied — the stay's departure, which is also the UK basic tax point for a completed stay.", "format": "date", "title": "Supply to", "type": "string" }, "tax_summary": { "description": "Per-rate bands, derived from the charges' own `tax_application` rows — the rule's rate, not a recomputation.", "items": { "properties": { "basis": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "code": { "type": "string" }, "inclusive": { "type": "boolean" }, "jurisdiction": { "type": "string" }, "name": { "type": "string" }, "rate": { "format": "decimal", "type": "string" }, "tax": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "rate", "basis", "tax" ], "type": "object" }, "title": "Invoice tax summary", "type": "array" }, "tax_total": { "description": "Tax total", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Invoice tax total", "type": "object" } }, "required": [ "number", "kind", "series", "sequence_value", "issued_on", "issued_at", "currency", "net_total", "tax_total", "gross_total", "amount_paid", "amount_due", "tax_summary", "lines", "issuer", "recipient_kind", "simplified", "language", "content_hash", "render_version" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.invoice:read" ] } ], "summary": "Read Invoice", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.invoice/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe numbered, sealed document a folio becomes when it is issued — a tax invoice, or a credit note reversing one. Carries snapshots of the issuer, the recipient, every ledger line and the per-rate tax bands, so the document renders from itself and never changes after issue.", "operationId": "get_hospitality_invoice_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.invoice" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.invoice:read" ] } ], "summary": "Read Invoice as of a watermark", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.invoice/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe numbered, sealed document a folio becomes when it is issued — a tax invoice, or a credit note reversing one. Carries snapshots of the issuer, the recipient, every ledger line and the per-rate tax bands, so the document renders from itself and never changes after issue.", "operationId": "list_links_hospitality_invoice", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.invoice:read" ] } ], "summary": "List links of Invoice", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.invoice_billed_to_company", "hospitality.link.invoice_billed_to_person", "hospitality.link.invoice_credits_invoice", "hospitality.link.invoice_for_folio", "hospitality.link.stored_object_for_invoice" ] } } ] }, "/v1/object-types/hospitality.invoice/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe numbered, sealed document a folio becomes when it is issued — a tax invoice, or a credit note reversing one. Carries snapshots of the issuer, the recipient, every ledger line and the per-rate tax bands, so the document renders from itself and never changes after issue.", "operationId": "traverse_hospitality_invoice", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.invoice_billed_to_company", "hospitality.link.invoice_billed_to_person", "hospitality.link.invoice_credits_invoice", "hospitality.link.invoice_for_folio", "hospitality.link.stored_object_for_invoice" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.invoice:read" ] } ], "summary": "Traverse from Invoice", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.invoice/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe numbered, sealed document a folio becomes when it is issued — a tax invoice, or a credit note reversing one. Carries snapshots of the issuer, the recipient, every ledger line and the per-rate tax bands, so the document renders from itself and never changes after issue.", "operationId": "search_hospitality_invoice", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "number" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "number" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "number" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "number" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "invoice", "credit_note" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "series" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "series" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "series" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "series" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sequence_value" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sequence_value" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sequence_value" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_on" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_on" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_on" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "supply_from" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "supply_from" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "supply_from" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "supply_to" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "supply_to" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "supply_to" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "due_on" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "due_on" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "due_on" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "currency" }, "type": { "const": "eq" }, "value": { "format": "iso-4217", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "net_total" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_total" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "gross_total" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "amount_paid" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "amount_due" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_summary" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "basis": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "code": { "type": "string" }, "inclusive": { "type": "boolean" }, "jurisdiction": { "type": "string" }, "name": { "type": "string" }, "rate": { "format": "decimal", "type": "string" }, "tax": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "rate", "basis", "tax" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "lines" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "bucket": { "type": "string" }, "business_day": { "format": "date", "type": "string" }, "description": { "type": "string" }, "gross": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "net": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "tax": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "business_day", "description", "net", "tax", "gross" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issuer" }, "type": { "const": "eq" }, "value": { "properties": { "address": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "type": "object" }, "bank_account": { "properties": { "account_name": { "type": "string" }, "account_number": { "type": "string" }, "bic": { "type": "string" }, "iban": { "type": "string" }, "sort_code": { "type": "string" } }, "type": "object" }, "company_registration_number": { "type": "string" }, "contact_email": { "type": "string" }, "contact_phone": { "type": "string" }, "legal_name": { "type": "string" }, "tax_registration_number": { "type": "string" }, "tax_registration_scheme": { "type": "string" } }, "required": [ "legal_name", "address", "tax_registration_scheme" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recipient" }, "type": { "const": "eq" }, "value": { "properties": { "address": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "type": "object" }, "company_name": { "type": "string" }, "email": { "type": "string" }, "kind": { "type": "string" }, "name": { "type": "string" }, "reference": { "type": "string" }, "tax_identifier": { "type": "string" } }, "required": [ "kind", "name" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recipient_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "person", "company" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "simplified" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "language" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "language" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "language" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "language" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "content_hash" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "content_hash" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "content_hash" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "content_hash" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "previous_hash" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "previous_hash" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "previous_hash" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "previous_hash" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "render_version" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "render_version" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "render_version" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "render_version" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "note" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "note" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "number", "kind", "series", "sequence_value", "issued_on", "issued_at", "supply_from", "supply_to", "due_on", "recipient_kind", "language", "content_hash", "previous_hash", "render_version", "note" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.invoice" }, "properties": { "additionalProperties": false, "properties": { "amount_due": { "description": "Zero on a settled stay; the transferred balance on a folio settled to a company's A/R account.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Invoice amount due", "type": "object" }, "amount_paid": { "description": "Amount paid", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Invoice amount paid", "type": "object" }, "content_hash": { "description": "SHA-256 over the canonical snapshot. With `previous_hash` this chains issued documents, which is what the modern fiscal regimes actually check — they put integrity on a chain over issued records rather than on the integer being dense.", "title": "Content hash", "type": "string" }, "currency": { "format": "iso-4217", "title": "Currency", "type": "string" }, "due_on": { "description": "Only set when `amount_due` is above zero — the company-billed case.", "format": "date", "title": "Payment due", "type": "string" }, "gross_total": { "description": "Gross total", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Invoice gross total", "type": "object" }, "issued_at": { "description": "The instant of issue. Also the renderer's fixed timestamp, which is what makes a re-render byte-identical to the stored PDF.", "format": "date-time", "title": "Issued at", "type": "string" }, "issued_on": { "description": "The property's business date of issue — an action parameter, never `Utc::now()`. This is the document's date for tax purposes.", "format": "date", "title": "Issue date", "type": "string" }, "issuer": { "description": "The property's legal identity, as it printed.", "properties": { "address": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "type": "object" }, "bank_account": { "properties": { "account_name": { "type": "string" }, "account_number": { "type": "string" }, "bic": { "type": "string" }, "iban": { "type": "string" }, "sort_code": { "type": "string" } }, "type": "object" }, "company_registration_number": { "type": "string" }, "contact_email": { "type": "string" }, "contact_phone": { "type": "string" }, "legal_name": { "type": "string" }, "tax_registration_number": { "type": "string" }, "tax_registration_scheme": { "type": "string" } }, "required": [ "legal_name", "address", "tax_registration_scheme" ], "title": "Invoice issuer", "type": "object" }, "kind": { "description": "`invoice`, or `credit_note` reversing one.", "enum": [ "invoice", "credit_note" ], "title": "Document kind", "type": "string" }, "language": { "description": "BCP 47 tag the document was rendered in.", "title": "Language", "type": "string" }, "lines": { "description": "The printed lines, snapshotted at issue.", "items": { "properties": { "bucket": { "type": "string" }, "business_day": { "format": "date", "type": "string" }, "description": { "type": "string" }, "gross": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "net": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "tax": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "business_day", "description", "net", "tax", "gross" ], "type": "object" }, "title": "Invoice lines", "type": "array" }, "net_total": { "description": "Net total", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Invoice net total", "type": "object" }, "note": { "title": "Note", "type": "string" }, "number": { "description": "The legal document number, e.g. `STAN-2026-000123`. Allocated from the property's series inside the issuing transaction and never reissued.", "title": "Invoice number", "type": "string" }, "previous_hash": { "description": "The previous issued document's `content_hash` — one chain per property, spanning invoices AND credit notes together, absent only for the property's first. Deliberately NOT per series: Spain's Orden HAC/1177/2024 art. 7(c) requires a system to produce \"una unica cadena\", and art. 7(d) that the chain carry both the alta and the anulacion records; Basque TicketBAI chains to the previous issued invoice regardless of series. The *number* series stays per kind; the chain is one strand. Backwards here makes Veri-factu a rebuild rather than a configuration.", "title": "Previous content hash", "type": "string" }, "recipient": { "description": "Who the document was addressed to, as it printed.", "properties": { "address": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "type": "object" }, "company_name": { "type": "string" }, "email": { "type": "string" }, "kind": { "type": "string" }, "name": { "type": "string" }, "reference": { "type": "string" }, "tax_identifier": { "type": "string" } }, "required": [ "kind", "name" ], "title": "Invoice recipient", "type": "object" }, "recipient_kind": { "description": "Unmarked twin of `recipient.kind`, so the board can filter company documents without reading the PII snapshot.", "enum": [ "person", "company" ], "title": "Recipient kind", "type": "string" }, "render_version": { "description": "Which renderer produced the stored PDF. A later engine upgrade may change bytes, so a re-render under a different version is a copy, not the original.", "title": "Renderer version", "type": "string" }, "sequence_value": { "description": "The bare counter value `number` was rendered from. Kept so a gap in a series is detectable without parsing the formatted number.", "title": "Sequence value", "type": "integer" }, "series": { "description": "The sequence this number came from — `{property_id}:{kind}:{yyyy}`. Series are annual and per document kind: France requires numbering that is chronological and continuous within a series, and a credit note sharing the invoice run cannot satisfy that.", "title": "Number series", "type": "string" }, "simplified": { "description": "Issued under the small-amount rule (UK £250, DE €250) without recipient details. Never true for a company recipient — the whole point of their document is input-tax recovery.", "title": "Simplified", "type": "boolean" }, "supply_from": { "description": "First day of the period supplied — the stay's arrival. Printed as the Leistungszeitraum.", "format": "date", "title": "Supply from", "type": "string" }, "supply_to": { "description": "Last day of the period supplied — the stay's departure, which is also the UK basic tax point for a completed stay.", "format": "date", "title": "Supply to", "type": "string" }, "tax_summary": { "description": "Per-rate bands, derived from the charges' own `tax_application` rows — the rule's rate, not a recomputation.", "items": { "properties": { "basis": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "code": { "type": "string" }, "inclusive": { "type": "boolean" }, "jurisdiction": { "type": "string" }, "name": { "type": "string" }, "rate": { "format": "decimal", "type": "string" }, "tax": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "rate", "basis", "tax" ], "type": "object" }, "title": "Invoice tax summary", "type": "array" }, "tax_total": { "description": "Tax total", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Invoice tax total", "type": "object" } }, "required": [ "number", "kind", "series", "sequence_value", "issued_on", "issued_at", "currency", "net_total", "tax_total", "gross_total", "amount_paid", "amount_due", "tax_summary", "lines", "issuer", "recipient_kind", "simplified", "language", "content_hash", "render_version" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.invoice:read" ] } ], "summary": "Search Invoice", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.item_class/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe behaviour bundle a menu item inherits: the tax class its VAT resolves through (with an optional takeaway override — cold food is zero-rated off the premises, VAT Notice 709/1 §4), the revenue category a room charge posts to the folio by (food / soft drinks / alcohol / other), the default course, and whether discounts and service charge apply.", "operationId": "get_hospitality_item_class", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.item_class" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Class code", "type": "string" }, "course_default": { "title": "Default course number for items of this class", "type": "integer" }, "description": { "title": "Operator-facing description", "type": "string" }, "discountable": { "title": "Discounts apply", "type": "boolean" }, "name": { "title": "Class name", "type": "string" }, "revenue_category": { "enum": [ "food", "non_alcoholic_beverage", "alcoholic_beverage", "other" ], "title": "Revenue category", "type": "string" }, "service_chargeable": { "title": "Service charge applies", "type": "boolean" }, "takeaway_tax_class": { "description": "The tax class used instead when the item leaves the premises (takeaway, delivery). Absent = the same as `tax_class` — hot food and drinks are standard-rated either way.", "title": "Takeaway tax class", "type": "string" }, "tax_class": { "description": "The tax class code the item's tax rules target (`tax_rule.tax_class`) when it is eaten on the premises — dine-in, in-room, breakfast. A class with no rule in force refuses to ring rather than selling at an unknown rate; a zero-rated class carries an explicit 0% rule.", "title": "Tax class", "type": "string" } }, "required": [ "code", "name", "tax_class", "revenue_category", "discountable", "service_chargeable" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.item_class:read" ] } ], "summary": "Read Item class", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.item_class/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe behaviour bundle a menu item inherits: the tax class its VAT resolves through (with an optional takeaway override — cold food is zero-rated off the premises, VAT Notice 709/1 §4), the revenue category a room charge posts to the folio by (food / soft drinks / alcohol / other), the default course, and whether discounts and service charge apply.", "operationId": "get_hospitality_item_class_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.item_class" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.item_class:read" ] } ], "summary": "Read Item class as of a watermark", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.item_class/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe behaviour bundle a menu item inherits: the tax class its VAT resolves through (with an optional takeaway override — cold food is zero-rated off the premises, VAT Notice 709/1 §4), the revenue category a room charge posts to the folio by (food / soft drinks / alcohol / other), the default course, and whether discounts and service charge apply.", "operationId": "list_links_hospitality_item_class", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.item_class:read" ] } ], "summary": "List links of Item class", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.menu_item_in_class" ] } } ] }, "/v1/object-types/hospitality.item_class/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe behaviour bundle a menu item inherits: the tax class its VAT resolves through (with an optional takeaway override — cold food is zero-rated off the premises, VAT Notice 709/1 §4), the revenue category a room charge posts to the folio by (food / soft drinks / alcohol / other), the default course, and whether discounts and service charge apply.", "operationId": "traverse_hospitality_item_class", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.menu_item_in_class" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.item_class:read" ] } ], "summary": "Traverse from Item class", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.item_class/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe behaviour bundle a menu item inherits: the tax class its VAT resolves through (with an optional takeaway override — cold food is zero-rated off the premises, VAT Notice 709/1 §4), the revenue category a room charge posts to the folio by (food / soft drinks / alcohol / other), the default course, and whether discounts and service charge apply.", "operationId": "search_hospitality_item_class", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_class" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_class" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_class" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_class" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "takeaway_tax_class" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "takeaway_tax_class" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "takeaway_tax_class" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "takeaway_tax_class" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revenue_category" }, "type": { "const": "eq" }, "value": { "enum": [ "food", "non_alcoholic_beverage", "alcoholic_beverage", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "course_default" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "course_default" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "course_default" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "discountable" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "service_chargeable" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "tax_class", "takeaway_tax_class", "revenue_category", "course_default", "description" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.item_class" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Class code", "type": "string" }, "course_default": { "title": "Default course number for items of this class", "type": "integer" }, "description": { "title": "Operator-facing description", "type": "string" }, "discountable": { "title": "Discounts apply", "type": "boolean" }, "name": { "title": "Class name", "type": "string" }, "revenue_category": { "enum": [ "food", "non_alcoholic_beverage", "alcoholic_beverage", "other" ], "title": "Revenue category", "type": "string" }, "service_chargeable": { "title": "Service charge applies", "type": "boolean" }, "takeaway_tax_class": { "description": "The tax class used instead when the item leaves the premises (takeaway, delivery). Absent = the same as `tax_class` — hot food and drinks are standard-rated either way.", "title": "Takeaway tax class", "type": "string" }, "tax_class": { "description": "The tax class code the item's tax rules target (`tax_rule.tax_class`) when it is eaten on the premises — dine-in, in-room, breakfast. A class with no rule in force refuses to ring rather than selling at an unknown rate; a zero-rated class carries an explicit 0% rule.", "title": "Tax class", "type": "string" } }, "required": [ "code", "name", "tax_class", "revenue_category", "discountable", "service_chargeable" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.item_class:read" ] } ], "summary": "Search Item class", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.item_price/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne menu price for a variant (price_for_variant), optionally narrowed to an outlet (price_at_outlet), an order kind (room-service pricing), a daypart (the bar's lunch price) and an effective window (a price rise from a date). A sale takes the most specific row in force — outlet beats any outlet, then order kind, then daypart — and two equally specific rows refuse to ring. `amount` is the price the guest sees: VAT-inclusive wherever the tax rule is inclusive (UK), net where it adds on.", "operationId": "get_hospitality_item_price", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.item_price" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "Menu price", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Item price amount", "type": "object" }, "daypart": { "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "title": "Only in this daypart (absent = any)", "type": "string" }, "effective_from": { "format": "date", "title": "First business date the price applies (inclusive; absent = always)", "type": "string" }, "effective_to": { "format": "date", "title": "Last business date the price applies (inclusive; absent = open-ended)", "type": "string" }, "id": { "title": "Price id", "type": "string" }, "order_kind": { "enum": [ "dine_in", "takeaway", "room_service", "delivery" ], "title": "Only for this order kind (absent = any)", "type": "string" } }, "required": [ "id", "amount" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.item_price:read" ] } ], "summary": "Read Item price", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.item_price/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne menu price for a variant (price_for_variant), optionally narrowed to an outlet (price_at_outlet), an order kind (room-service pricing), a daypart (the bar's lunch price) and an effective window (a price rise from a date). A sale takes the most specific row in force — outlet beats any outlet, then order kind, then daypart — and two equally specific rows refuse to ring. `amount` is the price the guest sees: VAT-inclusive wherever the tax rule is inclusive (UK), net where it adds on.", "operationId": "get_hospitality_item_price_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.item_price" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.item_price:read" ] } ], "summary": "Read Item price as of a watermark", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.item_price/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne menu price for a variant (price_for_variant), optionally narrowed to an outlet (price_at_outlet), an order kind (room-service pricing), a daypart (the bar's lunch price) and an effective window (a price rise from a date). A sale takes the most specific row in force — outlet beats any outlet, then order kind, then daypart — and two equally specific rows refuse to ring. `amount` is the price the guest sees: VAT-inclusive wherever the tax rule is inclusive (UK), net where it adds on.", "operationId": "list_links_hospitality_item_price", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.item_price:read" ] } ], "summary": "List links of Item price", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.price_at_outlet", "hospitality.link.price_for_variant" ] } } ] }, "/v1/object-types/hospitality.item_price/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne menu price for a variant (price_for_variant), optionally narrowed to an outlet (price_at_outlet), an order kind (room-service pricing), a daypart (the bar's lunch price) and an effective window (a price rise from a date). A sale takes the most specific row in force — outlet beats any outlet, then order kind, then daypart — and two equally specific rows refuse to ring. `amount` is the price the guest sees: VAT-inclusive wherever the tax rule is inclusive (UK), net where it adds on.", "operationId": "traverse_hospitality_item_price", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.price_at_outlet", "hospitality.link.price_for_variant" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.item_price:read" ] } ], "summary": "Traverse from Item price", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.item_price/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne menu price for a variant (price_for_variant), optionally narrowed to an outlet (price_at_outlet), an order kind (room-service pricing), a daypart (the bar's lunch price) and an effective window (a price rise from a date). A sale takes the most specific row in force — outlet beats any outlet, then order kind, then daypart — and two equally specific rows refuse to ring. `amount` is the price the guest sees: VAT-inclusive wherever the tax rule is inclusive (UK), net where it adds on.", "operationId": "search_hospitality_item_price", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "order_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "dine_in", "takeaway", "room_service", "delivery" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "daypart" }, "type": { "const": "eq" }, "value": { "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "order_kind", "daypart", "effective_from", "effective_to" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.item_price" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "Menu price", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Item price amount", "type": "object" }, "daypart": { "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "title": "Only in this daypart (absent = any)", "type": "string" }, "effective_from": { "format": "date", "title": "First business date the price applies (inclusive; absent = always)", "type": "string" }, "effective_to": { "format": "date", "title": "Last business date the price applies (inclusive; absent = open-ended)", "type": "string" }, "id": { "title": "Price id", "type": "string" }, "order_kind": { "enum": [ "dine_in", "takeaway", "room_service", "delivery" ], "title": "Only for this order kind (absent = any)", "type": "string" } }, "required": [ "id", "amount" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.item_price:read" ] } ], "summary": "Search Item price", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.kitchen_ticket/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe fulfilment view of one course's fired lines at one prep station — fire_course cuts one ticket per station per course (Toast coursing model). fired → bumped, with recall re-opening a bumped ticket; expo in-prep/ready states are bump-bar UI flow, not record states. Bump screens tail the fnb.* events on /v1/events/stream; the all-day aggregate is a render over the same events.", "operationId": "get_hospitality_kitchen_ticket", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.kitchen_ticket" }, "properties": { "additionalProperties": false, "properties": { "bumped_at": { "format": "date-time", "title": "When the ticket bumped (most recent bump)", "type": "string" }, "course_number": { "title": "Course", "type": "integer" }, "fired_at": { "format": "date-time", "title": "When the ticket hit the board", "type": "string" }, "id": { "title": "Ticket id", "type": "string" }, "recalled_at": { "format": "date-time", "title": "When the ticket was recalled (most recent recall)", "type": "string" }, "status": { "enum": [ "fired", "bumped", "recalled" ], "title": "Ticket lifecycle status", "type": "string" } }, "required": [ "id", "status", "course_number", "fired_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.kitchen_ticket:read" ] } ], "summary": "Read Kitchen ticket", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.kitchen_ticket/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe fulfilment view of one course's fired lines at one prep station — fire_course cuts one ticket per station per course (Toast coursing model). fired → bumped, with recall re-opening a bumped ticket; expo in-prep/ready states are bump-bar UI flow, not record states. Bump screens tail the fnb.* events on /v1/events/stream; the all-day aggregate is a render over the same events.", "operationId": "get_hospitality_kitchen_ticket_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.kitchen_ticket" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.kitchen_ticket:read" ] } ], "summary": "Read Kitchen ticket as of a watermark", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.kitchen_ticket/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe fulfilment view of one course's fired lines at one prep station — fire_course cuts one ticket per station per course (Toast coursing model). fired → bumped, with recall re-opening a bumped ticket; expo in-prep/ready states are bump-bar UI flow, not record states. Bump screens tail the fnb.* events on /v1/events/stream; the all-day aggregate is a render over the same events.", "operationId": "list_links_hospitality_kitchen_ticket", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.kitchen_ticket:read" ] } ], "summary": "List links of Kitchen ticket", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.check_line_on_ticket", "hospitality.link.ticket_at_station", "hospitality.link.ticket_for_check" ] } } ] }, "/v1/object-types/hospitality.kitchen_ticket/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe fulfilment view of one course's fired lines at one prep station — fire_course cuts one ticket per station per course (Toast coursing model). fired → bumped, with recall re-opening a bumped ticket; expo in-prep/ready states are bump-bar UI flow, not record states. Bump screens tail the fnb.* events on /v1/events/stream; the all-day aggregate is a render over the same events.", "operationId": "traverse_hospitality_kitchen_ticket", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.check_line_on_ticket", "hospitality.link.ticket_at_station", "hospitality.link.ticket_for_check" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.kitchen_ticket:read" ] } ], "summary": "Traverse from Kitchen ticket", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.kitchen_ticket/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe fulfilment view of one course's fired lines at one prep station — fire_course cuts one ticket per station per course (Toast coursing model). fired → bumped, with recall re-opening a bumped ticket; expo in-prep/ready states are bump-bar UI flow, not record states. Bump screens tail the fnb.* events on /v1/events/stream; the all-day aggregate is a render over the same events.", "operationId": "search_hospitality_kitchen_ticket", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "fired", "bumped", "recalled" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "course_number" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "course_number" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "course_number" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fired_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fired_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fired_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "bumped_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "bumped_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "bumped_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recalled_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recalled_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recalled_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "status", "course_number", "fired_at", "bumped_at", "recalled_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.kitchen_ticket" }, "properties": { "additionalProperties": false, "properties": { "bumped_at": { "format": "date-time", "title": "When the ticket bumped (most recent bump)", "type": "string" }, "course_number": { "title": "Course", "type": "integer" }, "fired_at": { "format": "date-time", "title": "When the ticket hit the board", "type": "string" }, "id": { "title": "Ticket id", "type": "string" }, "recalled_at": { "format": "date-time", "title": "When the ticket was recalled (most recent recall)", "type": "string" }, "status": { "enum": [ "fired", "bumped", "recalled" ], "title": "Ticket lifecycle status", "type": "string" } }, "required": [ "id", "status", "course_number", "fired_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.kitchen_ticket:read" ] } ], "summary": "Search Kitchen ticket", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.labour_ledger_entry/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne posted labour-cost amount — an auditable business record (provenance, void trail, optional link to staff and shift) exactly like a revenue charge. Aerandil records what the payroll system of record posted; it never computes pay. Multi-day pay-period imports post to `business_date` un-prorated in v1 (the accrual rule is the payroll system's); `period_start` / `period_end` preserve the source window.", "operationId": "get_hospitality_labour_ledger_entry", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.labour_ledger_entry" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "Amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Labour ledger entry amount", "type": "object" }, "business_date": { "format": "date", "title": "Business date", "type": "string" }, "department": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "it_services", "retail", "other_operated", "minor_operated", "administrative_general", "information_telecom_systems", "sales_marketing", "property_ops_maintenance", "utilities" ], "title": "USALI 12 Schedule 15 department", "type": "string" }, "external_ref": { "title": "External ref", "type": "string" }, "id": { "title": "Entry id", "type": "string" }, "kind": { "enum": [ "salaries_wages", "service_charges_distributed", "contracted_labour", "bonuses_incentives", "payroll_taxes", "supplemental_pay", "employee_benefits" ], "title": "USALI labour-cost kind", "type": "string" }, "period_end": { "format": "date", "title": "Pay-period end", "type": "string" }, "period_start": { "format": "date", "title": "Pay-period start", "type": "string" }, "posted_at": { "format": "date-time", "title": "Posted at", "type": "string" }, "source": { "enum": [ "timeclock", "payroll_import", "manual" ], "title": "Source", "type": "string" }, "voided": { "title": "Voided", "type": "boolean" } }, "required": [ "id", "kind", "department", "business_date", "source", "posted_at", "voided" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.labour_ledger_entry:read" ] } ], "summary": "Read Labour ledger entry", "tags": [ "labour" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.labour_ledger_entry/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne posted labour-cost amount — an auditable business record (provenance, void trail, optional link to staff and shift) exactly like a revenue charge. Aerandil records what the payroll system of record posted; it never computes pay. Multi-day pay-period imports post to `business_date` un-prorated in v1 (the accrual rule is the payroll system's); `period_start` / `period_end` preserve the source window.", "operationId": "get_hospitality_labour_ledger_entry_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.labour_ledger_entry" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.labour_ledger_entry:read" ] } ], "summary": "Read Labour ledger entry as of a watermark", "tags": [ "labour" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.labour_ledger_entry/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne posted labour-cost amount — an auditable business record (provenance, void trail, optional link to staff and shift) exactly like a revenue charge. Aerandil records what the payroll system of record posted; it never computes pay. Multi-day pay-period imports post to `business_date` un-prorated in v1 (the accrual rule is the payroll system's); `period_start` / `period_end` preserve the source window.", "operationId": "list_links_hospitality_labour_ledger_entry", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.labour_ledger_entry:read" ] } ], "summary": "List links of Labour ledger entry", "tags": [ "labour" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.labour_entry_at_property", "hospitality.link.labour_entry_for_shift", "hospitality.link.labour_entry_for_staff_member" ] } } ] }, "/v1/object-types/hospitality.labour_ledger_entry/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne posted labour-cost amount — an auditable business record (provenance, void trail, optional link to staff and shift) exactly like a revenue charge. Aerandil records what the payroll system of record posted; it never computes pay. Multi-day pay-period imports post to `business_date` un-prorated in v1 (the accrual rule is the payroll system's); `period_start` / `period_end` preserve the source window.", "operationId": "traverse_hospitality_labour_ledger_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.labour_entry_at_property", "hospitality.link.labour_entry_for_shift", "hospitality.link.labour_entry_for_staff_member" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.labour_ledger_entry:read" ] } ], "summary": "Traverse from Labour ledger entry", "tags": [ "labour" ] } }, "/v1/object-types/hospitality.labour_ledger_entry/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne posted labour-cost amount — an auditable business record (provenance, void trail, optional link to staff and shift) exactly like a revenue charge. Aerandil records what the payroll system of record posted; it never computes pay. Multi-day pay-period imports post to `business_date` un-prorated in v1 (the accrual rule is the payroll system's); `period_start` / `period_end` preserve the source window.", "operationId": "search_hospitality_labour_ledger_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "salaries_wages", "service_charges_distributed", "contracted_labour", "bonuses_incentives", "payroll_taxes", "supplemental_pay", "employee_benefits" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "department" }, "type": { "const": "eq" }, "value": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "it_services", "retail", "other_operated", "minor_operated", "administrative_general", "information_telecom_systems", "sales_marketing", "property_ops_maintenance", "utilities" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_start" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_start" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_start" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_end" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_end" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_end" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source" }, "type": { "const": "eq" }, "value": { "enum": [ "timeclock", "payroll_import", "manual" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "posted_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "posted_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "posted_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "voided" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "kind", "department", "business_date", "period_start", "period_end", "source", "external_ref", "posted_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.labour_ledger_entry" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "Amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Labour ledger entry amount", "type": "object" }, "business_date": { "format": "date", "title": "Business date", "type": "string" }, "department": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "it_services", "retail", "other_operated", "minor_operated", "administrative_general", "information_telecom_systems", "sales_marketing", "property_ops_maintenance", "utilities" ], "title": "USALI 12 Schedule 15 department", "type": "string" }, "external_ref": { "title": "External ref", "type": "string" }, "id": { "title": "Entry id", "type": "string" }, "kind": { "enum": [ "salaries_wages", "service_charges_distributed", "contracted_labour", "bonuses_incentives", "payroll_taxes", "supplemental_pay", "employee_benefits" ], "title": "USALI labour-cost kind", "type": "string" }, "period_end": { "format": "date", "title": "Pay-period end", "type": "string" }, "period_start": { "format": "date", "title": "Pay-period start", "type": "string" }, "posted_at": { "format": "date-time", "title": "Posted at", "type": "string" }, "source": { "enum": [ "timeclock", "payroll_import", "manual" ], "title": "Source", "type": "string" }, "voided": { "title": "Voided", "type": "boolean" } }, "required": [ "id", "kind", "department", "business_date", "source", "posted_at", "voided" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.labour_ledger_entry:read" ] } ], "summary": "Search Labour ledger entry", "tags": [ "labour" ] } }, "/v1/object-types/hospitality.longevity_assessment/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe opaque binding to an external clinical record for a member's longevity / diagnostic assessment. **Structural payload-empty contract** — no biomarker fields, no lab-value fields, no diagnostic-detail fields, ever. The clinical detail lives in the external clinical record (referenced via the mandatory `external_record_reference` link in commit 6); Aerandil holds only the opaque pointer. HIPAA / GDPR Article 9 special-category data stays in the source-of-truth system; Aerandil is structurally not a covered entity for this data.", "operationId": "get_hospitality_longevity_assessment", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.longevity_assessment" }, "properties": { "additionalProperties": false, "properties": { "assessed_at": { "format": "date-time", "title": "When the assessment was administered", "type": "string" }, "id": { "title": "Assessment id", "type": "string" }, "modalities_tested_ref": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.wellness_modality" }, "title": "Modalities covered (informational; outcomes live in external record)", "type": "array" }, "notes": { "title": "Operator's non-clinical observations (no biomarker / lab-value detail)", "type": "string" }, "summary_tags": { "items": { "type": "string" }, "title": "Operator-defined free-text tags (no clinical detail)", "type": "array" } }, "required": [ "id", "assessed_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.longevity_assessment:read" ] } ], "summary": "Read Longevity assessment", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.longevity_assessment/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe opaque binding to an external clinical record for a member's longevity / diagnostic assessment. **Structural payload-empty contract** — no biomarker fields, no lab-value fields, no diagnostic-detail fields, ever. The clinical detail lives in the external clinical record (referenced via the mandatory `external_record_reference` link in commit 6); Aerandil holds only the opaque pointer. HIPAA / GDPR Article 9 special-category data stays in the source-of-truth system; Aerandil is structurally not a covered entity for this data.", "operationId": "get_hospitality_longevity_assessment_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.longevity_assessment" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.longevity_assessment:read" ] } ], "summary": "Read Longevity assessment as of a watermark", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.longevity_assessment/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe opaque binding to an external clinical record for a member's longevity / diagnostic assessment. **Structural payload-empty contract** — no biomarker fields, no lab-value fields, no diagnostic-detail fields, ever. The clinical detail lives in the external clinical record (referenced via the mandatory `external_record_reference` link in commit 6); Aerandil holds only the opaque pointer. HIPAA / GDPR Article 9 special-category data stays in the source-of-truth system; Aerandil is structurally not a covered entity for this data.", "operationId": "list_links_hospitality_longevity_assessment", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.longevity_assessment:read" ] } ], "summary": "List links of Longevity assessment", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.assessment_for_membership", "hospitality.link.assessment_references_external_record" ] } } ] }, "/v1/object-types/hospitality.longevity_assessment/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe opaque binding to an external clinical record for a member's longevity / diagnostic assessment. **Structural payload-empty contract** — no biomarker fields, no lab-value fields, no diagnostic-detail fields, ever. The clinical detail lives in the external clinical record (referenced via the mandatory `external_record_reference` link in commit 6); Aerandil holds only the opaque pointer. HIPAA / GDPR Article 9 special-category data stays in the source-of-truth system; Aerandil is structurally not a covered entity for this data.", "operationId": "traverse_hospitality_longevity_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.assessment_for_membership", "hospitality.link.assessment_references_external_record" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.longevity_assessment:read" ] } ], "summary": "Traverse from Longevity assessment", "tags": [ "membership" ] } }, "/v1/object-types/hospitality.longevity_assessment/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe opaque binding to an external clinical record for a member's longevity / diagnostic assessment. **Structural payload-empty contract** — no biomarker fields, no lab-value fields, no diagnostic-detail fields, ever. The clinical detail lives in the external clinical record (referenced via the mandatory `external_record_reference` link in commit 6); Aerandil holds only the opaque pointer. HIPAA / GDPR Article 9 special-category data stays in the source-of-truth system; Aerandil is structurally not a covered entity for this data.", "operationId": "search_hospitality_longevity_assessment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "assessed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "assessed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "assessed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "summary_tags" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "modalities_tested_ref" }, "type": { "const": "eq" }, "value": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.wellness_modality" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "assessed_at", "notes" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.longevity_assessment" }, "properties": { "additionalProperties": false, "properties": { "assessed_at": { "format": "date-time", "title": "When the assessment was administered", "type": "string" }, "id": { "title": "Assessment id", "type": "string" }, "modalities_tested_ref": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.wellness_modality" }, "title": "Modalities covered (informational; outcomes live in external record)", "type": "array" }, "notes": { "title": "Operator's non-clinical observations (no biomarker / lab-value detail)", "type": "string" }, "summary_tags": { "items": { "type": "string" }, "title": "Operator-defined free-text tags (no clinical detail)", "type": "array" } }, "required": [ "id", "assessed_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.longevity_assessment:read" ] } ], "summary": "Search Longevity assessment", "tags": [ "membership" ] } }, "/v1/object-types/hospitality.lost_found_item/objects/{id}": { "get": { "description": "Read an existing instance.\n\nSomething left behind and found at the house. `found` where it was found — a room (`lost_found_item_in_room`) or a named place (`found_location`) — and by whom (`lost_found_item_found_by`, the staff member behind the handset); `stored` with where it is kept; `claimed` once a guest asks for it (`lost_found_item_claimed_by`); `returned` to the person it went to (`lost_found_item_returned_to`, `returned_at`); or `disposed` — donated, destroyed, handed to the police or released to the finder — with when and why. `returned` and `disposed` are terminal. The `description` says what the thing is, never whose: the owner is a link. The `id` is the tag written on the bag.", "operationId": "get_hospitality_lost_found_item", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.lost_found_item" }, "properties": { "additionalProperties": false, "properties": { "category": { "enum": [ "clothing", "electronics", "jewellery", "documents", "keys", "money", "toiletries", "other" ], "title": "What kind of thing it is (what a claim is matched on, and how it is kept)", "type": "string" }, "claimed_at": { "format": "date-time", "title": "When a guest asked for it", "type": "string" }, "description": { "title": "What it is — colour, make, distinguishing marks; not whose", "type": "string" }, "disposal_method": { "enum": [ "donated", "destroyed", "handed_to_police", "released_to_finder", "other" ], "title": "Donated, destroyed, handed to the police, released to the finder, or other", "type": "string" }, "disposal_reason": { "title": "Why it was not kept any longer (\"unclaimed past the 90-day hold\")", "type": "string" }, "disposed_at": { "format": "date-time", "title": "When the house stopped keeping it", "type": "string" }, "found_at": { "format": "date-time", "title": "When it was found", "type": "string" }, "found_location": { "title": "Where it was found, when not in a room (\"lobby bar\", \"pool deck\")", "type": "string" }, "id": { "title": "Item tag (written on the bag)", "type": "string" }, "returned_at": { "format": "date-time", "title": "When it was handed back or sent", "type": "string" }, "status": { "enum": [ "found", "stored", "claimed", "returned", "disposed" ], "title": "Found, stored, claimed, returned or disposed", "type": "string" }, "storage_location": { "title": "Where it is kept (\"HK office shelf 3\", \"front-office safe\")", "type": "string" } }, "required": [ "id", "description", "found_at", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.lost_found_item:read" ] } ], "summary": "Read Lost & found item", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.lost_found_item/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nSomething left behind and found at the house. `found` where it was found — a room (`lost_found_item_in_room`) or a named place (`found_location`) — and by whom (`lost_found_item_found_by`, the staff member behind the handset); `stored` with where it is kept; `claimed` once a guest asks for it (`lost_found_item_claimed_by`); `returned` to the person it went to (`lost_found_item_returned_to`, `returned_at`); or `disposed` — donated, destroyed, handed to the police or released to the finder — with when and why. `returned` and `disposed` are terminal. The `description` says what the thing is, never whose: the owner is a link. The `id` is the tag written on the bag.", "operationId": "get_hospitality_lost_found_item_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.lost_found_item" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.lost_found_item:read" ] } ], "summary": "Read Lost & found item as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.lost_found_item/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nSomething left behind and found at the house. `found` where it was found — a room (`lost_found_item_in_room`) or a named place (`found_location`) — and by whom (`lost_found_item_found_by`, the staff member behind the handset); `stored` with where it is kept; `claimed` once a guest asks for it (`lost_found_item_claimed_by`); `returned` to the person it went to (`lost_found_item_returned_to`, `returned_at`); or `disposed` — donated, destroyed, handed to the police or released to the finder — with when and why. `returned` and `disposed` are terminal. The `description` says what the thing is, never whose: the owner is a link. The `id` is the tag written on the bag.", "operationId": "list_links_hospitality_lost_found_item", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.lost_found_item:read" ] } ], "summary": "List links of Lost & found item", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.lost_found_item_claimed_by", "hospitality.link.lost_found_item_found_by", "hospitality.link.lost_found_item_in_room", "hospitality.link.lost_found_item_returned_to", "hospitality.link.stored_object_for_lost_found_item" ] } } ] }, "/v1/object-types/hospitality.lost_found_item/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nSomething left behind and found at the house. `found` where it was found — a room (`lost_found_item_in_room`) or a named place (`found_location`) — and by whom (`lost_found_item_found_by`, the staff member behind the handset); `stored` with where it is kept; `claimed` once a guest asks for it (`lost_found_item_claimed_by`); `returned` to the person it went to (`lost_found_item_returned_to`, `returned_at`); or `disposed` — donated, destroyed, handed to the police or released to the finder — with when and why. `returned` and `disposed` are terminal. The `description` says what the thing is, never whose: the owner is a link. The `id` is the tag written on the bag.", "operationId": "traverse_hospitality_lost_found_item", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.lost_found_item_claimed_by", "hospitality.link.lost_found_item_found_by", "hospitality.link.lost_found_item_in_room", "hospitality.link.lost_found_item_returned_to", "hospitality.link.stored_object_for_lost_found_item" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.lost_found_item:read" ] } ], "summary": "Traverse from Lost & found item", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.lost_found_item/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nSomething left behind and found at the house. `found` where it was found — a room (`lost_found_item_in_room`) or a named place (`found_location`) — and by whom (`lost_found_item_found_by`, the staff member behind the handset); `stored` with where it is kept; `claimed` once a guest asks for it (`lost_found_item_claimed_by`); `returned` to the person it went to (`lost_found_item_returned_to`, `returned_at`); or `disposed` — donated, destroyed, handed to the police or released to the finder — with when and why. `returned` and `disposed` are terminal. The `description` says what the thing is, never whose: the owner is a link. The `id` is the tag written on the bag.", "operationId": "search_hospitality_lost_found_item", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "category" }, "type": { "const": "eq" }, "value": { "enum": [ "clothing", "electronics", "jewellery", "documents", "keys", "money", "toiletries", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "found_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "found_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "found_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "found_location" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "found_location" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "found_location" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "found_location" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "found", "stored", "claimed", "returned", "disposed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "storage_location" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "storage_location" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "storage_location" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "storage_location" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "claimed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "claimed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "claimed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "returned_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "returned_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "returned_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "disposed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "disposed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "disposed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "disposal_method" }, "type": { "const": "eq" }, "value": { "enum": [ "donated", "destroyed", "handed_to_police", "released_to_finder", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "disposal_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "disposal_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "description", "category", "found_at", "found_location", "status", "storage_location", "claimed_at", "returned_at", "disposed_at", "disposal_method", "disposal_reason" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.lost_found_item" }, "properties": { "additionalProperties": false, "properties": { "category": { "enum": [ "clothing", "electronics", "jewellery", "documents", "keys", "money", "toiletries", "other" ], "title": "What kind of thing it is (what a claim is matched on, and how it is kept)", "type": "string" }, "claimed_at": { "format": "date-time", "title": "When a guest asked for it", "type": "string" }, "description": { "title": "What it is — colour, make, distinguishing marks; not whose", "type": "string" }, "disposal_method": { "enum": [ "donated", "destroyed", "handed_to_police", "released_to_finder", "other" ], "title": "Donated, destroyed, handed to the police, released to the finder, or other", "type": "string" }, "disposal_reason": { "title": "Why it was not kept any longer (\"unclaimed past the 90-day hold\")", "type": "string" }, "disposed_at": { "format": "date-time", "title": "When the house stopped keeping it", "type": "string" }, "found_at": { "format": "date-time", "title": "When it was found", "type": "string" }, "found_location": { "title": "Where it was found, when not in a room (\"lobby bar\", \"pool deck\")", "type": "string" }, "id": { "title": "Item tag (written on the bag)", "type": "string" }, "returned_at": { "format": "date-time", "title": "When it was handed back or sent", "type": "string" }, "status": { "enum": [ "found", "stored", "claimed", "returned", "disposed" ], "title": "Found, stored, claimed, returned or disposed", "type": "string" }, "storage_location": { "title": "Where it is kept (\"HK office shelf 3\", \"front-office safe\")", "type": "string" } }, "required": [ "id", "description", "found_at", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.lost_found_item:read" ] } ], "summary": "Search Lost & found item", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.loyalty_program/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA loyalty program — chain-points (Marriott Bonvoy), consortium-soft (LHW Leaders Club), membership-club (Soho House — defers to proposal 0005), or recognition-only (Aman Inner Circle). The four-archetype `program_type` is labelling over more granular axes (qualification cycle, expiry, redemption, `has_points_subsystem`, `is_published_to_member`); the schema admits configurations between archetypes — Preferred I Prefer = `consortium_soft + has_points_subsystem`; SLH-Hilton = `consortium_soft AND chain_points`. Recognition is always-on across all archetypes — the `program_type` does not gate it.", "operationId": "get_hospitality_loyalty_program", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.loyalty_program" }, "properties": { "additionalProperties": false, "properties": { "allowed_channels": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.channel" }, "title": "Allowed booking channels (SLH-Hilton-style allow-list)", "type": "array" }, "co_brand_card_partners": { "items": { "type": "string" }, "title": "Co-brand card partners (free-text until points_partner ships)", "type": "array" }, "code": { "title": "Program code", "type": "string" }, "effective_from": { "format": "date-time", "title": "Effective from", "type": "string" }, "effective_to": { "format": "date-time", "title": "Effective to (null when current)", "type": "string" }, "expiry_rule": { "enum": [ "inactivity_months", "hard_expiry_months", "none" ], "title": "Expiry rule", "type": "string" }, "expiry_value_months": { "title": "Expiry threshold (months; required when expiry_rule != none)", "type": "integer" }, "family_pooling_policy": { "description": "Family pooling policy (gated)", "properties": { "allowed": { "type": "boolean" }, "fee_per_pool": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "max_members": { "type": "integer" }, "tier_gated_to": { "items": { "type": "string" }, "type": "array" } }, "required": [ "allowed" ], "title": "Loyalty program family pooling policy", "type": "object" }, "has_points_subsystem": { "title": "Carries a points-liability subsystem", "type": "boolean" }, "id": { "title": "Program id", "type": "string" }, "lifetime_status_enabled": { "title": "Lifetime tiers offered (Marriott Lifetime Platinum etc.)", "type": "boolean" }, "name": { "title": "Program name", "type": "string" }, "program_type": { "enum": [ "chain_points", "consortium_soft", "membership_club", "recognition_only" ], "title": "Program type (labelling)", "type": "string" }, "redemption_blackout_policy": { "enum": [ "none", "capacity_controlled", "restricted_dates" ], "title": "Redemption blackout policy (gated)", "type": "string" }, "tier_qualification_policy": { "description": "Tier qualification policy", "properties": { "is_published_to_member": { "type": "boolean" }, "kind": { "enum": [ "annual_nights_or_spend", "annual_points", "lifetime_points", "dues_continuity", "discretionary", "invitation_only", "observed_frequency" ], "type": "string" }, "rollover_policy": { "enum": [ "none", "rollover_credits", "rollover_points" ], "type": "string" }, "thresholds": {} }, "required": [ "kind", "thresholds", "rollover_policy", "is_published_to_member" ], "title": "Loyalty program tier qualification policy", "type": "object" } }, "required": [ "id", "code", "name", "program_type", "has_points_subsystem", "lifetime_status_enabled", "expiry_rule", "tier_qualification_policy", "effective_from" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.loyalty_program:read" ] } ], "summary": "Read Loyalty program", "tags": [ "loyalty" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.loyalty_program/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA loyalty program — chain-points (Marriott Bonvoy), consortium-soft (LHW Leaders Club), membership-club (Soho House — defers to proposal 0005), or recognition-only (Aman Inner Circle). The four-archetype `program_type` is labelling over more granular axes (qualification cycle, expiry, redemption, `has_points_subsystem`, `is_published_to_member`); the schema admits configurations between archetypes — Preferred I Prefer = `consortium_soft + has_points_subsystem`; SLH-Hilton = `consortium_soft AND chain_points`. Recognition is always-on across all archetypes — the `program_type` does not gate it.", "operationId": "get_hospitality_loyalty_program_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.loyalty_program" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.loyalty_program:read" ] } ], "summary": "Read Loyalty program as of a watermark", "tags": [ "loyalty" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.loyalty_program/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA loyalty program — chain-points (Marriott Bonvoy), consortium-soft (LHW Leaders Club), membership-club (Soho House — defers to proposal 0005), or recognition-only (Aman Inner Circle). The four-archetype `program_type` is labelling over more granular axes (qualification cycle, expiry, redemption, `has_points_subsystem`, `is_published_to_member`); the schema admits configurations between archetypes — Preferred I Prefer = `consortium_soft + has_points_subsystem`; SLH-Hilton = `consortium_soft AND chain_points`. Recognition is always-on across all archetypes — the `program_type` does not gate it.", "operationId": "list_links_hospitality_loyalty_program", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.loyalty_program:read" ] } ], "summary": "List links of Loyalty program", "tags": [ "loyalty" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.loyalty_program_at_brand", "hospitality.link.loyalty_program_at_property", "hospitality.link.loyalty_program_for_consortium", "hospitality.link.recognition_event_for_program" ] } } ] }, "/v1/object-types/hospitality.loyalty_program/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA loyalty program — chain-points (Marriott Bonvoy), consortium-soft (LHW Leaders Club), membership-club (Soho House — defers to proposal 0005), or recognition-only (Aman Inner Circle). The four-archetype `program_type` is labelling over more granular axes (qualification cycle, expiry, redemption, `has_points_subsystem`, `is_published_to_member`); the schema admits configurations between archetypes — Preferred I Prefer = `consortium_soft + has_points_subsystem`; SLH-Hilton = `consortium_soft AND chain_points`. Recognition is always-on across all archetypes — the `program_type` does not gate it.", "operationId": "traverse_hospitality_loyalty_program", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.loyalty_program_at_brand", "hospitality.link.loyalty_program_at_property", "hospitality.link.loyalty_program_for_consortium", "hospitality.link.recognition_event_for_program" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.loyalty_program:read" ] } ], "summary": "Traverse from Loyalty program", "tags": [ "loyalty" ] } }, "/v1/object-types/hospitality.loyalty_program/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA loyalty program — chain-points (Marriott Bonvoy), consortium-soft (LHW Leaders Club), membership-club (Soho House — defers to proposal 0005), or recognition-only (Aman Inner Circle). The four-archetype `program_type` is labelling over more granular axes (qualification cycle, expiry, redemption, `has_points_subsystem`, `is_published_to_member`); the schema admits configurations between archetypes — Preferred I Prefer = `consortium_soft + has_points_subsystem`; SLH-Hilton = `consortium_soft AND chain_points`. Recognition is always-on across all archetypes — the `program_type` does not gate it.", "operationId": "search_hospitality_loyalty_program", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "program_type" }, "type": { "const": "eq" }, "value": { "enum": [ "chain_points", "consortium_soft", "membership_club", "recognition_only" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "has_points_subsystem" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "lifetime_status_enabled" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expiry_rule" }, "type": { "const": "eq" }, "value": { "enum": [ "inactivity_months", "hard_expiry_months", "none" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expiry_value_months" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expiry_value_months" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expiry_value_months" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tier_qualification_policy" }, "type": { "const": "eq" }, "value": { "properties": { "is_published_to_member": { "type": "boolean" }, "kind": { "enum": [ "annual_nights_or_spend", "annual_points", "lifetime_points", "dues_continuity", "discretionary", "invitation_only", "observed_frequency" ], "type": "string" }, "rollover_policy": { "enum": [ "none", "rollover_credits", "rollover_points" ], "type": "string" }, "thresholds": {} }, "required": [ "kind", "thresholds", "rollover_policy", "is_published_to_member" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "redemption_blackout_policy" }, "type": { "const": "eq" }, "value": { "enum": [ "none", "capacity_controlled", "restricted_dates" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "family_pooling_policy" }, "type": { "const": "eq" }, "value": { "properties": { "allowed": { "type": "boolean" }, "fee_per_pool": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "max_members": { "type": "integer" }, "tier_gated_to": { "items": { "type": "string" }, "type": "array" } }, "required": [ "allowed" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "allowed_channels" }, "type": { "const": "eq" }, "value": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.channel" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "co_brand_card_partners" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "code", "name", "program_type", "expiry_rule", "expiry_value_months", "redemption_blackout_policy", "effective_from", "effective_to" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.loyalty_program" }, "properties": { "additionalProperties": false, "properties": { "allowed_channels": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.channel" }, "title": "Allowed booking channels (SLH-Hilton-style allow-list)", "type": "array" }, "co_brand_card_partners": { "items": { "type": "string" }, "title": "Co-brand card partners (free-text until points_partner ships)", "type": "array" }, "code": { "title": "Program code", "type": "string" }, "effective_from": { "format": "date-time", "title": "Effective from", "type": "string" }, "effective_to": { "format": "date-time", "title": "Effective to (null when current)", "type": "string" }, "expiry_rule": { "enum": [ "inactivity_months", "hard_expiry_months", "none" ], "title": "Expiry rule", "type": "string" }, "expiry_value_months": { "title": "Expiry threshold (months; required when expiry_rule != none)", "type": "integer" }, "family_pooling_policy": { "description": "Family pooling policy (gated)", "properties": { "allowed": { "type": "boolean" }, "fee_per_pool": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "max_members": { "type": "integer" }, "tier_gated_to": { "items": { "type": "string" }, "type": "array" } }, "required": [ "allowed" ], "title": "Loyalty program family pooling policy", "type": "object" }, "has_points_subsystem": { "title": "Carries a points-liability subsystem", "type": "boolean" }, "id": { "title": "Program id", "type": "string" }, "lifetime_status_enabled": { "title": "Lifetime tiers offered (Marriott Lifetime Platinum etc.)", "type": "boolean" }, "name": { "title": "Program name", "type": "string" }, "program_type": { "enum": [ "chain_points", "consortium_soft", "membership_club", "recognition_only" ], "title": "Program type (labelling)", "type": "string" }, "redemption_blackout_policy": { "enum": [ "none", "capacity_controlled", "restricted_dates" ], "title": "Redemption blackout policy (gated)", "type": "string" }, "tier_qualification_policy": { "description": "Tier qualification policy", "properties": { "is_published_to_member": { "type": "boolean" }, "kind": { "enum": [ "annual_nights_or_spend", "annual_points", "lifetime_points", "dues_continuity", "discretionary", "invitation_only", "observed_frequency" ], "type": "string" }, "rollover_policy": { "enum": [ "none", "rollover_credits", "rollover_points" ], "type": "string" }, "thresholds": {} }, "required": [ "kind", "thresholds", "rollover_policy", "is_published_to_member" ], "title": "Loyalty program tier qualification policy", "type": "object" } }, "required": [ "id", "code", "name", "program_type", "has_points_subsystem", "lifetime_status_enabled", "expiry_rule", "tier_qualification_policy", "effective_from" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.loyalty_program:read" ] } ], "summary": "Search Loyalty program", "tags": [ "loyalty" ] } }, "/v1/object-types/hospitality.maintenance_plan/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA room's preventive-maintenance cadence: the work order to raise (title, category, severity), how often — `fixed` to the calendar or `floating` from the last completion, every `interval_days` — and when it is next due. Holds state only; the automation lane is its clock: a sweep over plans whose due instant has come — `next_due_at`, the house's own midnight starting `next_due_on` — raises the work order (`raise_maintenance_work_order`, the plan goes `raised`), and a monitor on that order reaching complete or void moves the plan on (`advance_maintenance_plan`, back to `scheduled` with the next due date). One open order per plan at a time.", "operationId": "get_hospitality_maintenance_plan", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.maintenance_plan" }, "properties": { "additionalProperties": false, "properties": { "cadence": { "enum": [ "fixed", "floating" ], "title": "Fixed to the calendar, or floating from the last completion", "type": "string" }, "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "Category of the raised work orders", "type": "string" }, "description": { "title": "Detail carried onto each raised work order", "type": "string" }, "id": { "title": "Maintenance plan id", "type": "string" }, "interval_days": { "title": "Days between occurrences", "type": "integer" }, "last_completed_on": { "format": "date", "title": "The property-local date its last work order was completed", "type": "string" }, "last_raised_at": { "format": "date-time", "title": "When the plan last raised a work order", "type": "string" }, "next_due_at": { "format": "date-time", "title": "The instant the house's day reaches next_due_on — its local midnight in the property's timezone (UTC midnight when it has none); what the raise sweep compares with the lane's clock, written beside next_due_on by the plan's verbs", "type": "string" }, "next_due_on": { "format": "date", "title": "The date the next work order is due", "type": "string" }, "retired_at": { "format": "date-time", "title": "When the plan was retired", "type": "string" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "title": "Severity of the raised work orders", "type": "string" }, "status": { "enum": [ "scheduled", "raised", "retired" ], "title": "Scheduled (waiting for its date), raised (its order is open), or retired", "type": "string" }, "title": { "title": "What the raised work order says to do", "type": "string" } }, "required": [ "id", "title", "category", "severity", "cadence", "interval_days", "next_due_on", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.maintenance_plan:read" ] } ], "summary": "Read Maintenance plan", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.maintenance_plan/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA room's preventive-maintenance cadence: the work order to raise (title, category, severity), how often — `fixed` to the calendar or `floating` from the last completion, every `interval_days` — and when it is next due. Holds state only; the automation lane is its clock: a sweep over plans whose due instant has come — `next_due_at`, the house's own midnight starting `next_due_on` — raises the work order (`raise_maintenance_work_order`, the plan goes `raised`), and a monitor on that order reaching complete or void moves the plan on (`advance_maintenance_plan`, back to `scheduled` with the next due date). One open order per plan at a time.", "operationId": "get_hospitality_maintenance_plan_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.maintenance_plan" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.maintenance_plan:read" ] } ], "summary": "Read Maintenance plan as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.maintenance_plan/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA room's preventive-maintenance cadence: the work order to raise (title, category, severity), how often — `fixed` to the calendar or `floating` from the last completion, every `interval_days` — and when it is next due. Holds state only; the automation lane is its clock: a sweep over plans whose due instant has come — `next_due_at`, the house's own midnight starting `next_due_on` — raises the work order (`raise_maintenance_work_order`, the plan goes `raised`), and a monitor on that order reaching complete or void moves the plan on (`advance_maintenance_plan`, back to `scheduled` with the next due date). One open order per plan at a time.", "operationId": "list_links_hospitality_maintenance_plan", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.maintenance_plan:read" ] } ], "summary": "List links of Maintenance plan", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.maintenance_plan_for_asset", "hospitality.link.maintenance_plan_for_room", "hospitality.link.work_order_from_maintenance_plan" ] } } ] }, "/v1/object-types/hospitality.maintenance_plan/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA room's preventive-maintenance cadence: the work order to raise (title, category, severity), how often — `fixed` to the calendar or `floating` from the last completion, every `interval_days` — and when it is next due. Holds state only; the automation lane is its clock: a sweep over plans whose due instant has come — `next_due_at`, the house's own midnight starting `next_due_on` — raises the work order (`raise_maintenance_work_order`, the plan goes `raised`), and a monitor on that order reaching complete or void moves the plan on (`advance_maintenance_plan`, back to `scheduled` with the next due date). One open order per plan at a time.", "operationId": "traverse_hospitality_maintenance_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.maintenance_plan_for_asset", "hospitality.link.maintenance_plan_for_room", "hospitality.link.work_order_from_maintenance_plan" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.maintenance_plan:read" ] } ], "summary": "Traverse from Maintenance plan", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.maintenance_plan/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA room's preventive-maintenance cadence: the work order to raise (title, category, severity), how often — `fixed` to the calendar or `floating` from the last completion, every `interval_days` — and when it is next due. Holds state only; the automation lane is its clock: a sweep over plans whose due instant has come — `next_due_at`, the house's own midnight starting `next_due_on` — raises the work order (`raise_maintenance_work_order`, the plan goes `raised`), and a monitor on that order reaching complete or void moves the plan on (`advance_maintenance_plan`, back to `scheduled` with the next due date). One open order per plan at a time.", "operationId": "search_hospitality_maintenance_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "title" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "title" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "title" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "title" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "category" }, "type": { "const": "eq" }, "value": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "severity" }, "type": { "const": "eq" }, "value": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cadence" }, "type": { "const": "eq" }, "value": { "enum": [ "fixed", "floating" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "interval_days" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "interval_days" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "interval_days" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_due_on" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_due_on" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_due_on" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_due_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_due_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_due_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "scheduled", "raised", "retired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_raised_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_raised_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_raised_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_completed_on" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_completed_on" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_completed_on" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "title", "description", "category", "severity", "cadence", "interval_days", "next_due_on", "next_due_at", "status", "last_raised_at", "last_completed_on", "retired_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.maintenance_plan" }, "properties": { "additionalProperties": false, "properties": { "cadence": { "enum": [ "fixed", "floating" ], "title": "Fixed to the calendar, or floating from the last completion", "type": "string" }, "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "Category of the raised work orders", "type": "string" }, "description": { "title": "Detail carried onto each raised work order", "type": "string" }, "id": { "title": "Maintenance plan id", "type": "string" }, "interval_days": { "title": "Days between occurrences", "type": "integer" }, "last_completed_on": { "format": "date", "title": "The property-local date its last work order was completed", "type": "string" }, "last_raised_at": { "format": "date-time", "title": "When the plan last raised a work order", "type": "string" }, "next_due_at": { "format": "date-time", "title": "The instant the house's day reaches next_due_on — its local midnight in the property's timezone (UTC midnight when it has none); what the raise sweep compares with the lane's clock, written beside next_due_on by the plan's verbs", "type": "string" }, "next_due_on": { "format": "date", "title": "The date the next work order is due", "type": "string" }, "retired_at": { "format": "date-time", "title": "When the plan was retired", "type": "string" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "title": "Severity of the raised work orders", "type": "string" }, "status": { "enum": [ "scheduled", "raised", "retired" ], "title": "Scheduled (waiting for its date), raised (its order is open), or retired", "type": "string" }, "title": { "title": "What the raised work order says to do", "type": "string" } }, "required": [ "id", "title", "category", "severity", "cadence", "interval_days", "next_due_on", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.maintenance_plan:read" ] } ], "summary": "Search Maintenance plan", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.management_agreement/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA hotel management agreement (HMA): one owner company engages the operator to run one or more properties. Carries the terms that make the relationship inspectable — fee schedule, delegation thresholds, and the two-prong performance test — but never computes a fee: computed amounts post as `brand_operator_cost_entry` rows (counterparty = operator) and the monthly `owner_statement` records what was reported. Field defaults calibrate from executed EDGAR-filed HMAs and the HVS contract surveys (synth/docs/archetype4-research.md).", "operationId": "get_hospitality_management_agreement", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.management_agreement" }, "properties": { "additionalProperties": false, "properties": { "accounting_fee_monthly": { "description": "Centralised-accounting charge per month (Chatham disclosure: $1,200–1,500)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Management agreement accounting fee monthly", "type": "object" }, "base_fee_pct_revenue": { "format": "decimal", "title": "Base management fee as a fraction of total operating revenue (survey band 0.02–0.04, 0.03 the mode)", "type": "string" }, "budget_aggregate_flex_pct": { "format": "decimal", "title": "Aggregate budget overspend ceiling without approval (Condor: 0.05)", "type": "string" }, "budget_line_flex_pct": { "format": "decimal", "title": "Per-line-item overspend the operator may commit without approval (Condor: 0.10)", "type": "string" }, "capex_approval_threshold": { "description": "Spend above this needs owner approval (PHR: $25k contracts, $100k major renovations)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Management agreement capex approval threshold", "type": "object" }, "code": { "title": "Agreement code", "type": "string" }, "commenced_on": { "format": "date", "title": "Commencement date", "type": "string" }, "contract_approval_threshold": { "description": "Contract value above this (or term > 1 year) needs owner approval", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Management agreement contract approval threshold", "type": "object" }, "cure_window_months": { "title": "Months the operator has to cure a performance failure", "type": "integer" }, "external_ref": { "title": "External ref", "type": "string" }, "incentive_kind": { "enum": [ "pct_agop_over_priority", "pct_noi_attainment", "none" ], "title": "Incentive-fee structure", "type": "string" }, "incentive_pct": { "format": "decimal", "title": "Incentive fee fraction (of AGOP above priority, or of the attainment-scaled base — per incentive_kind)", "type": "string" }, "initial_term_years": { "title": "Initial term (years; third-party norm 5–10, brand-manager 20+)", "type": "integer" }, "name": { "title": "Agreement name", "type": "string" }, "noi_budget_floor_pct": { "format": "decimal", "title": "Performance test prong 1: minimum actual/budgeted NOI (Strand & Condor: 0.90)", "type": "string" }, "owner_priority_return_pct": { "format": "decimal", "title": "Owner's priority return hurdle as a fraction of investment (survey band 0.08–0.12); incentive_kind = pct_agop_over_priority only", "type": "string" }, "radius_miles": { "format": "decimal", "title": "Area-of-protection radius — no competing managed hotel within it (Strand: 5; Condor: 3)", "type": "string" }, "revenue_management_fee_monthly": { "description": "Centralised revenue-management charge per month (Chatham disclosure: $1,000)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Management agreement revenue management fee monthly", "type": "object" }, "revpar_index_floor_pct": { "format": "decimal", "title": "Performance test prong 2: minimum RevPAR index vs prior year (Strand: 1.00 per-hotel / 0.95 portfolio; Condor: 0.90)", "type": "string" }, "status": { "enum": [ "active", "terminated", "expired" ], "title": "Lifecycle status", "type": "string" }, "terminated_on": { "format": "date", "title": "Termination effective date", "type": "string" }, "termination_kind": { "enum": [ "performance", "sale_of_property", "for_cause", "without_cause" ], "title": "Why the agreement ended", "type": "string" }, "termination_reason": { "title": "Free-text termination note", "type": "string" } }, "required": [ "code", "name", "status", "commenced_on", "initial_term_years", "incentive_kind" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.management_agreement:read" ] } ], "summary": "Read Management agreement", "tags": [ "management" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.management_agreement/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA hotel management agreement (HMA): one owner company engages the operator to run one or more properties. Carries the terms that make the relationship inspectable — fee schedule, delegation thresholds, and the two-prong performance test — but never computes a fee: computed amounts post as `brand_operator_cost_entry` rows (counterparty = operator) and the monthly `owner_statement` records what was reported. Field defaults calibrate from executed EDGAR-filed HMAs and the HVS contract surveys (synth/docs/archetype4-research.md).", "operationId": "get_hospitality_management_agreement_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.management_agreement" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.management_agreement:read" ] } ], "summary": "Read Management agreement as of a watermark", "tags": [ "management" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.management_agreement/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA hotel management agreement (HMA): one owner company engages the operator to run one or more properties. Carries the terms that make the relationship inspectable — fee schedule, delegation thresholds, and the two-prong performance test — but never computes a fee: computed amounts post as `brand_operator_cost_entry` rows (counterparty = operator) and the monthly `owner_statement` records what was reported. Field defaults calibrate from executed EDGAR-filed HMAs and the HVS contract surveys (synth/docs/archetype4-research.md).", "operationId": "list_links_hospitality_management_agreement", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.management_agreement:read" ] } ], "summary": "List links of Management agreement", "tags": [ "management" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.management_agreement_covers_property", "hospitality.link.management_agreement_with_company", "hospitality.link.owner_statement_under_agreement" ] } } ] }, "/v1/object-types/hospitality.management_agreement/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA hotel management agreement (HMA): one owner company engages the operator to run one or more properties. Carries the terms that make the relationship inspectable — fee schedule, delegation thresholds, and the two-prong performance test — but never computes a fee: computed amounts post as `brand_operator_cost_entry` rows (counterparty = operator) and the monthly `owner_statement` records what was reported. Field defaults calibrate from executed EDGAR-filed HMAs and the HVS contract surveys (synth/docs/archetype4-research.md).", "operationId": "traverse_hospitality_management_agreement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.management_agreement_covers_property", "hospitality.link.management_agreement_with_company", "hospitality.link.owner_statement_under_agreement" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.management_agreement:read" ] } ], "summary": "Traverse from Management agreement", "tags": [ "management" ] } }, "/v1/object-types/hospitality.management_agreement/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA hotel management agreement (HMA): one owner company engages the operator to run one or more properties. Carries the terms that make the relationship inspectable — fee schedule, delegation thresholds, and the two-prong performance test — but never computes a fee: computed amounts post as `brand_operator_cost_entry` rows (counterparty = operator) and the monthly `owner_statement` records what was reported. Field defaults calibrate from executed EDGAR-filed HMAs and the HVS contract surveys (synth/docs/archetype4-research.md).", "operationId": "search_hospitality_management_agreement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "terminated", "expired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commenced_on" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commenced_on" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commenced_on" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "initial_term_years" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "initial_term_years" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "initial_term_years" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "base_fee_pct_revenue" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "base_fee_pct_revenue" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "base_fee_pct_revenue" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "incentive_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "pct_agop_over_priority", "pct_noi_attainment", "none" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "incentive_pct" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "incentive_pct" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "incentive_pct" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "owner_priority_return_pct" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "owner_priority_return_pct" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "owner_priority_return_pct" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "accounting_fee_monthly" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revenue_management_fee_monthly" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "capex_approval_threshold" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contract_approval_threshold" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "budget_line_flex_pct" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "budget_line_flex_pct" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "budget_line_flex_pct" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "budget_aggregate_flex_pct" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "budget_aggregate_flex_pct" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "budget_aggregate_flex_pct" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "noi_budget_floor_pct" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "noi_budget_floor_pct" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "noi_budget_floor_pct" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revpar_index_floor_pct" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revpar_index_floor_pct" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revpar_index_floor_pct" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cure_window_months" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cure_window_months" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cure_window_months" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "radius_miles" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "radius_miles" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "radius_miles" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "terminated_on" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "terminated_on" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "terminated_on" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "termination_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "performance", "sale_of_property", "for_cause", "without_cause" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "termination_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "termination_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "termination_reason" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "termination_reason" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "status", "commenced_on", "initial_term_years", "base_fee_pct_revenue", "incentive_kind", "incentive_pct", "owner_priority_return_pct", "budget_line_flex_pct", "budget_aggregate_flex_pct", "noi_budget_floor_pct", "revpar_index_floor_pct", "cure_window_months", "radius_miles", "terminated_on", "termination_kind", "termination_reason", "external_ref" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.management_agreement" }, "properties": { "additionalProperties": false, "properties": { "accounting_fee_monthly": { "description": "Centralised-accounting charge per month (Chatham disclosure: $1,200–1,500)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Management agreement accounting fee monthly", "type": "object" }, "base_fee_pct_revenue": { "format": "decimal", "title": "Base management fee as a fraction of total operating revenue (survey band 0.02–0.04, 0.03 the mode)", "type": "string" }, "budget_aggregate_flex_pct": { "format": "decimal", "title": "Aggregate budget overspend ceiling without approval (Condor: 0.05)", "type": "string" }, "budget_line_flex_pct": { "format": "decimal", "title": "Per-line-item overspend the operator may commit without approval (Condor: 0.10)", "type": "string" }, "capex_approval_threshold": { "description": "Spend above this needs owner approval (PHR: $25k contracts, $100k major renovations)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Management agreement capex approval threshold", "type": "object" }, "code": { "title": "Agreement code", "type": "string" }, "commenced_on": { "format": "date", "title": "Commencement date", "type": "string" }, "contract_approval_threshold": { "description": "Contract value above this (or term > 1 year) needs owner approval", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Management agreement contract approval threshold", "type": "object" }, "cure_window_months": { "title": "Months the operator has to cure a performance failure", "type": "integer" }, "external_ref": { "title": "External ref", "type": "string" }, "incentive_kind": { "enum": [ "pct_agop_over_priority", "pct_noi_attainment", "none" ], "title": "Incentive-fee structure", "type": "string" }, "incentive_pct": { "format": "decimal", "title": "Incentive fee fraction (of AGOP above priority, or of the attainment-scaled base — per incentive_kind)", "type": "string" }, "initial_term_years": { "title": "Initial term (years; third-party norm 5–10, brand-manager 20+)", "type": "integer" }, "name": { "title": "Agreement name", "type": "string" }, "noi_budget_floor_pct": { "format": "decimal", "title": "Performance test prong 1: minimum actual/budgeted NOI (Strand & Condor: 0.90)", "type": "string" }, "owner_priority_return_pct": { "format": "decimal", "title": "Owner's priority return hurdle as a fraction of investment (survey band 0.08–0.12); incentive_kind = pct_agop_over_priority only", "type": "string" }, "radius_miles": { "format": "decimal", "title": "Area-of-protection radius — no competing managed hotel within it (Strand: 5; Condor: 3)", "type": "string" }, "revenue_management_fee_monthly": { "description": "Centralised revenue-management charge per month (Chatham disclosure: $1,000)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Management agreement revenue management fee monthly", "type": "object" }, "revpar_index_floor_pct": { "format": "decimal", "title": "Performance test prong 2: minimum RevPAR index vs prior year (Strand: 1.00 per-hotel / 0.95 portfolio; Condor: 0.90)", "type": "string" }, "status": { "enum": [ "active", "terminated", "expired" ], "title": "Lifecycle status", "type": "string" }, "terminated_on": { "format": "date", "title": "Termination effective date", "type": "string" }, "termination_kind": { "enum": [ "performance", "sale_of_property", "for_cause", "without_cause" ], "title": "Why the agreement ended", "type": "string" }, "termination_reason": { "title": "Free-text termination note", "type": "string" } }, "required": [ "code", "name", "status", "commenced_on", "initial_term_years", "incentive_kind" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.management_agreement:read" ] } ], "summary": "Search Management agreement", "tags": [ "management" ] } }, "/v1/object-types/hospitality.material/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA part or a product a house keeps — a spare part, a consumable, an amenity, linen, a minibar product, a laundry item, a cleaning product (hubOS's materials, laundry products and minibar families). Keyed by `code` within its catalogue: a brand's (`material_at_brand`, shared by the brand's houses) or one house's (`material_at_property`); `define_material` with a code the catalogue holds re-states it in place. Counted in its `unit`, which is fixed once any store holds it. A minibar product carries the `sale_price` a minibar task charges the in-house guest. `active`, or `retired` for good (the code stays taken). How much each store holds is its `stock_level` rows.", "operationId": "get_hospitality_material", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.material" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "The catalogue's code for it — unique within the catalogue", "type": "string" }, "defined_at": { "format": "date-time", "title": "When it was first put in the catalogue", "type": "string" }, "description": { "title": "Notes on it", "type": "string" }, "family": { "enum": [ "spare_part", "consumable", "amenity", "linen", "minibar_product", "laundry_item", "cleaning_product", "other" ], "title": "What kind of thing it is: spare_part, consumable, amenity, linen, minibar_product, laundry_item, cleaning_product, other", "type": "string" }, "name": { "title": "What it is, in words (\"Cola 330 ml\", \"GU10 lamp 5 W\")", "type": "string" }, "retire_reason": { "title": "Why it was retired — discontinued, replaced", "type": "string" }, "retired_at": { "format": "date-time", "title": "When it was retired", "type": "string" }, "sale_price": { "description": "What one unit sells for — what a minibar task charges the guest per unit", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Material sale price", "type": "object" }, "status": { "enum": [ "active", "retired" ], "title": "active, or retired (final)", "type": "string" }, "unit": { "enum": [ "each", "pack", "pair", "roll", "kg", "l", "m" ], "title": "The unit every quantity of it is counted in", "type": "string" } }, "required": [ "code", "name", "family", "unit", "status", "defined_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.material:read" ] } ], "summary": "Read Material", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.material/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA part or a product a house keeps — a spare part, a consumable, an amenity, linen, a minibar product, a laundry item, a cleaning product (hubOS's materials, laundry products and minibar families). Keyed by `code` within its catalogue: a brand's (`material_at_brand`, shared by the brand's houses) or one house's (`material_at_property`); `define_material` with a code the catalogue holds re-states it in place. Counted in its `unit`, which is fixed once any store holds it. A minibar product carries the `sale_price` a minibar task charges the in-house guest. `active`, or `retired` for good (the code stays taken). How much each store holds is its `stock_level` rows.", "operationId": "get_hospitality_material_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.material" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.material:read" ] } ], "summary": "Read Material as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.material/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA part or a product a house keeps — a spare part, a consumable, an amenity, linen, a minibar product, a laundry item, a cleaning product (hubOS's materials, laundry products and minibar families). Keyed by `code` within its catalogue: a brand's (`material_at_brand`, shared by the brand's houses) or one house's (`material_at_property`); `define_material` with a code the catalogue holds re-states it in place. Counted in its `unit`, which is fixed once any store holds it. A minibar product carries the `sale_price` a minibar task charges the in-house guest. `active`, or `retired` for good (the code stays taken). How much each store holds is its `stock_level` rows.", "operationId": "list_links_hospitality_material", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.material:read" ] } ], "summary": "List links of Material", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.material_at_brand", "hospitality.link.material_at_property", "hospitality.link.stock_level_for_material" ] } } ] }, "/v1/object-types/hospitality.material/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA part or a product a house keeps — a spare part, a consumable, an amenity, linen, a minibar product, a laundry item, a cleaning product (hubOS's materials, laundry products and minibar families). Keyed by `code` within its catalogue: a brand's (`material_at_brand`, shared by the brand's houses) or one house's (`material_at_property`); `define_material` with a code the catalogue holds re-states it in place. Counted in its `unit`, which is fixed once any store holds it. A minibar product carries the `sale_price` a minibar task charges the in-house guest. `active`, or `retired` for good (the code stays taken). How much each store holds is its `stock_level` rows.", "operationId": "traverse_hospitality_material", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.material_at_brand", "hospitality.link.material_at_property", "hospitality.link.stock_level_for_material" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.material:read" ] } ], "summary": "Traverse from Material", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.material/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA part or a product a house keeps — a spare part, a consumable, an amenity, linen, a minibar product, a laundry item, a cleaning product (hubOS's materials, laundry products and minibar families). Keyed by `code` within its catalogue: a brand's (`material_at_brand`, shared by the brand's houses) or one house's (`material_at_property`); `define_material` with a code the catalogue holds re-states it in place. Counted in its `unit`, which is fixed once any store holds it. A minibar product carries the `sale_price` a minibar task charges the in-house guest. `active`, or `retired` for good (the code stays taken). How much each store holds is its `stock_level` rows.", "operationId": "search_hospitality_material", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "family" }, "type": { "const": "eq" }, "value": { "enum": [ "spare_part", "consumable", "amenity", "linen", "minibar_product", "laundry_item", "cleaning_product", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "unit" }, "type": { "const": "eq" }, "value": { "enum": [ "each", "pack", "pair", "roll", "kg", "l", "m" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sale_price" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "retired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "defined_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "defined_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "defined_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retire_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retire_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "family", "unit", "description", "status", "defined_at", "retired_at", "retire_reason" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.material" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "The catalogue's code for it — unique within the catalogue", "type": "string" }, "defined_at": { "format": "date-time", "title": "When it was first put in the catalogue", "type": "string" }, "description": { "title": "Notes on it", "type": "string" }, "family": { "enum": [ "spare_part", "consumable", "amenity", "linen", "minibar_product", "laundry_item", "cleaning_product", "other" ], "title": "What kind of thing it is: spare_part, consumable, amenity, linen, minibar_product, laundry_item, cleaning_product, other", "type": "string" }, "name": { "title": "What it is, in words (\"Cola 330 ml\", \"GU10 lamp 5 W\")", "type": "string" }, "retire_reason": { "title": "Why it was retired — discontinued, replaced", "type": "string" }, "retired_at": { "format": "date-time", "title": "When it was retired", "type": "string" }, "sale_price": { "description": "What one unit sells for — what a minibar task charges the guest per unit", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Material sale price", "type": "object" }, "status": { "enum": [ "active", "retired" ], "title": "active, or retired (final)", "type": "string" }, "unit": { "enum": [ "each", "pack", "pair", "roll", "kg", "l", "m" ], "title": "The unit every quantity of it is counted in", "type": "string" } }, "required": [ "code", "name", "family", "unit", "status", "defined_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.material:read" ] } ], "summary": "Search Material", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.membership/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe individual access-bearing record. Distinct from `membership_account` because the account is the durable identity (one per primary member) and the membership is the access entitlement (one per primary + N per dependents). The Mindbody Premier factoring of Membership vs Pricing Option (commit 3's subscription) carries the distinction. One operator-journey from Saint Haven member → Saint Haven Founders → Saint Haven Founders + Equinox Hotel partner-tier is three rows; the underlying `membership_account` row is one.", "operationId": "get_hospitality_membership", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" }, "properties": { "additionalProperties": false, "properties": { "access_credentials_text": { "title": "Access-control credential identifier (free text — vendor-specific)", "type": "string" }, "access_status": { "enum": [ "active", "suspended", "frozen", "terminated" ], "title": "Access status", "type": "string" }, "dependency_kind": { "enum": [ "primary", "spouse", "child", "registered_member", "transferred_legacy" ], "title": "Relationship to the account (primary / spouse / child / registered / legacy)", "type": "string" }, "enrolment_kind": { "enum": [ "direct_enrolment", "inherited", "gifted", "reciprocity", "corporate_seat" ], "title": "How the membership came to exist", "type": "string" }, "id": { "title": "Membership id", "type": "string" }, "notes": { "title": "Operator notes", "type": "string" }, "person_ref": { "format": "uuid", "title": "Person who exercises the membership (typed reference)", "type": "string", "x-aerandil-references": "hospitality.person" } }, "required": [ "id", "enrolment_kind", "access_status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.membership:read" ] } ], "summary": "Read Membership", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.membership/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe individual access-bearing record. Distinct from `membership_account` because the account is the durable identity (one per primary member) and the membership is the access entitlement (one per primary + N per dependents). The Mindbody Premier factoring of Membership vs Pricing Option (commit 3's subscription) carries the distinction. One operator-journey from Saint Haven member → Saint Haven Founders → Saint Haven Founders + Equinox Hotel partner-tier is three rows; the underlying `membership_account` row is one.", "operationId": "get_hospitality_membership_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.membership" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.membership:read" ] } ], "summary": "Read Membership as of a watermark", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.membership/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe individual access-bearing record. Distinct from `membership_account` because the account is the durable identity (one per primary member) and the membership is the access entitlement (one per primary + N per dependents). The Mindbody Premier factoring of Membership vs Pricing Option (commit 3's subscription) carries the distinction. One operator-journey from Saint Haven member → Saint Haven Founders → Saint Haven Founders + Equinox Hotel partner-tier is three rows; the underlying `membership_account` row is one.", "operationId": "list_links_hospitality_membership", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.membership:read" ] } ], "summary": "List links of Membership", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.assessment_for_membership", "hospitality.link.coaching_plan_for_membership", "hospitality.link.membership_account_has_membership", "hospitality.link.membership_at_property", "hospitality.link.membership_at_tier", "hospitality.link.membership_for_person", "hospitality.link.membership_grants_access_at_property", "hospitality.link.wellness_protocol_for_membership", "hospitality.link.workflow_run_targets_membership" ] } } ] }, "/v1/object-types/hospitality.membership/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe individual access-bearing record. Distinct from `membership_account` because the account is the durable identity (one per primary member) and the membership is the access entitlement (one per primary + N per dependents). The Mindbody Premier factoring of Membership vs Pricing Option (commit 3's subscription) carries the distinction. One operator-journey from Saint Haven member → Saint Haven Founders → Saint Haven Founders + Equinox Hotel partner-tier is three rows; the underlying `membership_account` row is one.", "operationId": "traverse_hospitality_membership", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.assessment_for_membership", "hospitality.link.coaching_plan_for_membership", "hospitality.link.membership_account_has_membership", "hospitality.link.membership_at_property", "hospitality.link.membership_at_tier", "hospitality.link.membership_for_person", "hospitality.link.membership_grants_access_at_property", "hospitality.link.wellness_protocol_for_membership", "hospitality.link.workflow_run_targets_membership" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.membership:read" ] } ], "summary": "Traverse from Membership", "tags": [ "membership" ] } }, "/v1/object-types/hospitality.membership/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe individual access-bearing record. Distinct from `membership_account` because the account is the durable identity (one per primary member) and the membership is the access entitlement (one per primary + N per dependents). The Mindbody Premier factoring of Membership vs Pricing Option (commit 3's subscription) carries the distinction. One operator-journey from Saint Haven member → Saint Haven Founders → Saint Haven Founders + Equinox Hotel partner-tier is three rows; the underlying `membership_account` row is one.", "operationId": "search_hospitality_membership", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dependency_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "primary", "spouse", "child", "registered_member", "transferred_legacy" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "enrolment_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "direct_enrolment", "inherited", "gifted", "reciprocity", "corporate_seat" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "access_status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "suspended", "frozen", "terminated" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "person_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.person" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "access_credentials_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "access_credentials_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "access_credentials_text" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "access_credentials_text" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "dependency_kind", "enrolment_kind", "access_status", "access_credentials_text", "notes" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership" }, "properties": { "additionalProperties": false, "properties": { "access_credentials_text": { "title": "Access-control credential identifier (free text — vendor-specific)", "type": "string" }, "access_status": { "enum": [ "active", "suspended", "frozen", "terminated" ], "title": "Access status", "type": "string" }, "dependency_kind": { "enum": [ "primary", "spouse", "child", "registered_member", "transferred_legacy" ], "title": "Relationship to the account (primary / spouse / child / registered / legacy)", "type": "string" }, "enrolment_kind": { "enum": [ "direct_enrolment", "inherited", "gifted", "reciprocity", "corporate_seat" ], "title": "How the membership came to exist", "type": "string" }, "id": { "title": "Membership id", "type": "string" }, "notes": { "title": "Operator notes", "type": "string" }, "person_ref": { "format": "uuid", "title": "Person who exercises the membership (typed reference)", "type": "string", "x-aerandil-references": "hospitality.person" } }, "required": [ "id", "enrolment_kind", "access_status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.membership:read" ] } ], "summary": "Search Membership", "tags": [ "membership" ] } }, "/v1/object-types/hospitality.membership_account/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe durable identity that survives every membership transition — upgrade, downgrade, freeze, cancellation, renewal. One per primary member; dependents (spouse, children, registered companions) attach under it as separate `membership` rows (commit 2). Distinct from the individual access-bearing `membership` because the account identity is what the operator tracks for billing (one subscription per account in commit 3), recognition (the long arc of the member-property relationship), and clinical-record binding (assessments attach to an individual membership, but the family unit lives on the account). The Mindbody Premier factoring of Pricing Option vs Membership vs Autopay vs Contract is the load-bearing reference for why account and access record are separate primitives.", "operationId": "get_hospitality_membership_account", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership_account" }, "properties": { "additionalProperties": false, "properties": { "home_property_ref": { "format": "uuid", "title": "Home property — where the member primarily exercises access", "type": "string", "x-aerandil-references": "hospitality.property" }, "id": { "title": "Account id", "type": "string" }, "joined_at": { "format": "date-time", "title": "When the primary member first enrolled", "type": "string" }, "marketing_consent_inherits_from_person": { "title": "Marketing consent inherits from primary person (GDPR / CCPA)", "type": "boolean" }, "member_number": { "title": "Operator-side member number", "type": "string" }, "notes": { "title": "Operator notes", "type": "string" }, "primary_person_ref": { "format": "uuid", "title": "Primary member (typed reference to person)", "type": "string", "x-aerandil-references": "hospitality.person" }, "referred_by_text": { "title": "Referrer (free text — referrer may not be in the system)", "type": "string" }, "status": { "enum": [ "active", "frozen", "terminated", "legacy_lifetime" ], "title": "Account status", "type": "string" } }, "required": [ "id", "joined_at", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.membership_account:read" ] } ], "summary": "Read Membership account", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.membership_account/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe durable identity that survives every membership transition — upgrade, downgrade, freeze, cancellation, renewal. One per primary member; dependents (spouse, children, registered companions) attach under it as separate `membership` rows (commit 2). Distinct from the individual access-bearing `membership` because the account identity is what the operator tracks for billing (one subscription per account in commit 3), recognition (the long arc of the member-property relationship), and clinical-record binding (assessments attach to an individual membership, but the family unit lives on the account). The Mindbody Premier factoring of Pricing Option vs Membership vs Autopay vs Contract is the load-bearing reference for why account and access record are separate primitives.", "operationId": "get_hospitality_membership_account_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.membership_account" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.membership_account:read" ] } ], "summary": "Read Membership account as of a watermark", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.membership_account/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe durable identity that survives every membership transition — upgrade, downgrade, freeze, cancellation, renewal. One per primary member; dependents (spouse, children, registered companions) attach under it as separate `membership` rows (commit 2). Distinct from the individual access-bearing `membership` because the account identity is what the operator tracks for billing (one subscription per account in commit 3), recognition (the long arc of the member-property relationship), and clinical-record binding (assessments attach to an individual membership, but the family unit lives on the account). The Mindbody Premier factoring of Pricing Option vs Membership vs Autopay vs Contract is the load-bearing reference for why account and access record are separate primitives.", "operationId": "list_links_hospitality_membership_account", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.membership_account:read" ] } ], "summary": "List links of Membership account", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.membership_account_has_membership", "hospitality.link.membership_initiation_for_account", "hospitality.link.membership_subscription_for_account" ] } } ] }, "/v1/object-types/hospitality.membership_account/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe durable identity that survives every membership transition — upgrade, downgrade, freeze, cancellation, renewal. One per primary member; dependents (spouse, children, registered companions) attach under it as separate `membership` rows (commit 2). Distinct from the individual access-bearing `membership` because the account identity is what the operator tracks for billing (one subscription per account in commit 3), recognition (the long arc of the member-property relationship), and clinical-record binding (assessments attach to an individual membership, but the family unit lives on the account). The Mindbody Premier factoring of Pricing Option vs Membership vs Autopay vs Contract is the load-bearing reference for why account and access record are separate primitives.", "operationId": "traverse_hospitality_membership_account", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.membership_account_has_membership", "hospitality.link.membership_initiation_for_account", "hospitality.link.membership_subscription_for_account" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.membership_account:read" ] } ], "summary": "Traverse from Membership account", "tags": [ "membership" ] } }, "/v1/object-types/hospitality.membership_account/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe durable identity that survives every membership transition — upgrade, downgrade, freeze, cancellation, renewal. One per primary member; dependents (spouse, children, registered companions) attach under it as separate `membership` rows (commit 2). Distinct from the individual access-bearing `membership` because the account identity is what the operator tracks for billing (one subscription per account in commit 3), recognition (the long arc of the member-property relationship), and clinical-record binding (assessments attach to an individual membership, but the family unit lives on the account). The Mindbody Premier factoring of Pricing Option vs Membership vs Autopay vs Contract is the load-bearing reference for why account and access record are separate primitives.", "operationId": "search_hospitality_membership_account", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "member_number" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "member_number" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "member_number" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "member_number" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "joined_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "joined_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "joined_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "frozen", "terminated", "legacy_lifetime" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "primary_person_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.person" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "home_property_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "referred_by_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "referred_by_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "referred_by_text" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "referred_by_text" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "marketing_consent_inherits_from_person" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "member_number", "joined_at", "status", "referred_by_text", "notes" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership_account" }, "properties": { "additionalProperties": false, "properties": { "home_property_ref": { "format": "uuid", "title": "Home property — where the member primarily exercises access", "type": "string", "x-aerandil-references": "hospitality.property" }, "id": { "title": "Account id", "type": "string" }, "joined_at": { "format": "date-time", "title": "When the primary member first enrolled", "type": "string" }, "marketing_consent_inherits_from_person": { "title": "Marketing consent inherits from primary person (GDPR / CCPA)", "type": "boolean" }, "member_number": { "title": "Operator-side member number", "type": "string" }, "notes": { "title": "Operator notes", "type": "string" }, "primary_person_ref": { "format": "uuid", "title": "Primary member (typed reference to person)", "type": "string", "x-aerandil-references": "hospitality.person" }, "referred_by_text": { "title": "Referrer (free text — referrer may not be in the system)", "type": "string" }, "status": { "enum": [ "active", "frozen", "terminated", "legacy_lifetime" ], "title": "Account status", "type": "string" } }, "required": [ "id", "joined_at", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.membership_account:read" ] } ], "summary": "Search Membership account", "tags": [ "membership" ] } }, "/v1/object-types/hospitality.membership_initiation/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe one-time-charge artefact for tiers that carry a non-recurring initiation fee. Aman Founders' $200K, Saint Haven and Soho House joining fees, country-club initiation. Distinct from `membership_subscription` because the initiation is a non-recurring contract obligation with its own transferability rules (Aman Founders' legacy-lifetime transfers on Founder death; most other operators' initiations are non-transferable) and its own IFRS 15 / ASC 606 deferred-revenue treatment.", "operationId": "get_hospitality_membership_initiation", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership_initiation" }, "properties": { "additionalProperties": false, "properties": { "amortisation_method": { "enum": [ "straight_line_lifetime", "straight_line_years", "none" ], "title": "Deferred-revenue treatment intent (IFRS 15 / ASC 606)", "type": "string" }, "amortisation_years": { "title": "Amortisation years (required when amortisation_method = straight_line_years)", "type": "integer" }, "amount": { "description": "Initiation amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Membership initiation amount", "type": "object" }, "currency": { "format": "iso-4217", "title": "Currency (ISO 4217)", "type": "string" }, "id": { "title": "Initiation id", "type": "string" }, "legacy_lifetime": { "title": "Grants lifetime membership independent of subscription lapses", "type": "boolean" }, "notes": { "title": "Operator notes", "type": "string" }, "paid_at": { "format": "date-time", "title": "When the initiation was settled", "type": "string" }, "transferable": { "title": "Initiation transfers to a legacy successor", "type": "boolean" } }, "required": [ "id", "currency", "paid_at", "transferable", "legacy_lifetime" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.membership_initiation:read" ] } ], "summary": "Read Membership initiation", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.membership_initiation/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe one-time-charge artefact for tiers that carry a non-recurring initiation fee. Aman Founders' $200K, Saint Haven and Soho House joining fees, country-club initiation. Distinct from `membership_subscription` because the initiation is a non-recurring contract obligation with its own transferability rules (Aman Founders' legacy-lifetime transfers on Founder death; most other operators' initiations are non-transferable) and its own IFRS 15 / ASC 606 deferred-revenue treatment.", "operationId": "get_hospitality_membership_initiation_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.membership_initiation" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.membership_initiation:read" ] } ], "summary": "Read Membership initiation as of a watermark", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.membership_initiation/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe one-time-charge artefact for tiers that carry a non-recurring initiation fee. Aman Founders' $200K, Saint Haven and Soho House joining fees, country-club initiation. Distinct from `membership_subscription` because the initiation is a non-recurring contract obligation with its own transferability rules (Aman Founders' legacy-lifetime transfers on Founder death; most other operators' initiations are non-transferable) and its own IFRS 15 / ASC 606 deferred-revenue treatment.", "operationId": "list_links_hospitality_membership_initiation", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.membership_initiation:read" ] } ], "summary": "List links of Membership initiation", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.membership_initiation_for_account" ] } } ] }, "/v1/object-types/hospitality.membership_initiation/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe one-time-charge artefact for tiers that carry a non-recurring initiation fee. Aman Founders' $200K, Saint Haven and Soho House joining fees, country-club initiation. Distinct from `membership_subscription` because the initiation is a non-recurring contract obligation with its own transferability rules (Aman Founders' legacy-lifetime transfers on Founder death; most other operators' initiations are non-transferable) and its own IFRS 15 / ASC 606 deferred-revenue treatment.", "operationId": "traverse_hospitality_membership_initiation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.membership_initiation_for_account" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.membership_initiation:read" ] } ], "summary": "Traverse from Membership initiation", "tags": [ "membership" ] } }, "/v1/object-types/hospitality.membership_initiation/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe one-time-charge artefact for tiers that carry a non-recurring initiation fee. Aman Founders' $200K, Saint Haven and Soho House joining fees, country-club initiation. Distinct from `membership_subscription` because the initiation is a non-recurring contract obligation with its own transferability rules (Aman Founders' legacy-lifetime transfers on Founder death; most other operators' initiations are non-transferable) and its own IFRS 15 / ASC 606 deferred-revenue treatment.", "operationId": "search_hospitality_membership_initiation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "currency" }, "type": { "const": "eq" }, "value": { "format": "iso-4217", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "paid_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "paid_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "paid_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "transferable" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "legacy_lifetime" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "amortisation_method" }, "type": { "const": "eq" }, "value": { "enum": [ "straight_line_lifetime", "straight_line_years", "none" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "amortisation_years" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "amortisation_years" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "amortisation_years" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "paid_at", "amortisation_method", "amortisation_years", "notes" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership_initiation" }, "properties": { "additionalProperties": false, "properties": { "amortisation_method": { "enum": [ "straight_line_lifetime", "straight_line_years", "none" ], "title": "Deferred-revenue treatment intent (IFRS 15 / ASC 606)", "type": "string" }, "amortisation_years": { "title": "Amortisation years (required when amortisation_method = straight_line_years)", "type": "integer" }, "amount": { "description": "Initiation amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Membership initiation amount", "type": "object" }, "currency": { "format": "iso-4217", "title": "Currency (ISO 4217)", "type": "string" }, "id": { "title": "Initiation id", "type": "string" }, "legacy_lifetime": { "title": "Grants lifetime membership independent of subscription lapses", "type": "boolean" }, "notes": { "title": "Operator notes", "type": "string" }, "paid_at": { "format": "date-time", "title": "When the initiation was settled", "type": "string" }, "transferable": { "title": "Initiation transfers to a legacy successor", "type": "boolean" } }, "required": [ "id", "currency", "paid_at", "transferable", "legacy_lifetime" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.membership_initiation:read" ] } ], "summary": "Search Membership initiation", "tags": [ "membership" ] } }, "/v1/object-types/hospitality.membership_subscription/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe recurring billing primitive. Distinct from `membership` because the subscription is the contract+autopay shape (Mindbody Premier's separation), not the access entitlement. One member who downgrades from monthly to quarterly billing keeps the same membership but transitions to a new subscription row. The subscription attaches to the account, not to an individual membership — a family rate spans the primary + dependent memberships under one contract.", "operationId": "get_hospitality_membership_subscription", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership_subscription" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "Recurring amount per cycle", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Membership subscription amount", "type": "object" }, "auto_renew": { "title": "Auto-renew (autopay flag)", "type": "boolean" }, "cadence": { "enum": [ "monthly", "quarterly", "semi_annual", "annual", "multi_year" ], "title": "Billing cadence", "type": "string" }, "cadence_value": { "title": "Cadence value (for multi_year, the number of years; else 1)", "type": "integer" }, "contract_terms_text": { "title": "Contract-terms snapshot at signing (design-spec §B.2)", "type": "string" }, "currency": { "format": "iso-4217", "title": "Currency (ISO 4217)", "type": "string" }, "expected_end_date": { "format": "date", "title": "Expected end (null for open-ended autopay)", "type": "string" }, "id": { "title": "Subscription id", "type": "string" }, "next_billing_date": { "format": "date", "title": "Next scheduled charge date", "type": "string" }, "start_date": { "format": "date", "title": "Subscription start", "type": "string" }, "suspension_started_at": { "format": "date-time", "title": "When suspension started (required when suspension_state != none)", "type": "string" }, "suspension_state": { "enum": [ "none", "medically_suspended", "operator_paused", "self_paused" ], "title": "Suspension state (typed reason)", "type": "string" } }, "required": [ "id", "currency", "cadence", "cadence_value", "start_date", "auto_renew" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.membership_subscription:read" ] } ], "summary": "Read Membership subscription", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.membership_subscription/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe recurring billing primitive. Distinct from `membership` because the subscription is the contract+autopay shape (Mindbody Premier's separation), not the access entitlement. One member who downgrades from monthly to quarterly billing keeps the same membership but transitions to a new subscription row. The subscription attaches to the account, not to an individual membership — a family rate spans the primary + dependent memberships under one contract.", "operationId": "get_hospitality_membership_subscription_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.membership_subscription" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.membership_subscription:read" ] } ], "summary": "Read Membership subscription as of a watermark", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.membership_subscription/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe recurring billing primitive. Distinct from `membership` because the subscription is the contract+autopay shape (Mindbody Premier's separation), not the access entitlement. One member who downgrades from monthly to quarterly billing keeps the same membership but transitions to a new subscription row. The subscription attaches to the account, not to an individual membership — a family rate spans the primary + dependent memberships under one contract.", "operationId": "list_links_hospitality_membership_subscription", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.membership_subscription:read" ] } ], "summary": "List links of Membership subscription", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.membership_subscription_for_account" ] } } ] }, "/v1/object-types/hospitality.membership_subscription/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe recurring billing primitive. Distinct from `membership` because the subscription is the contract+autopay shape (Mindbody Premier's separation), not the access entitlement. One member who downgrades from monthly to quarterly billing keeps the same membership but transitions to a new subscription row. The subscription attaches to the account, not to an individual membership — a family rate spans the primary + dependent memberships under one contract.", "operationId": "traverse_hospitality_membership_subscription", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.membership_subscription_for_account" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.membership_subscription:read" ] } ], "summary": "Traverse from Membership subscription", "tags": [ "membership" ] } }, "/v1/object-types/hospitality.membership_subscription/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe recurring billing primitive. Distinct from `membership` because the subscription is the contract+autopay shape (Mindbody Premier's separation), not the access entitlement. One member who downgrades from monthly to quarterly billing keeps the same membership but transitions to a new subscription row. The subscription attaches to the account, not to an individual membership — a family rate spans the primary + dependent memberships under one contract.", "operationId": "search_hospitality_membership_subscription", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "currency" }, "type": { "const": "eq" }, "value": { "format": "iso-4217", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cadence" }, "type": { "const": "eq" }, "value": { "enum": [ "monthly", "quarterly", "semi_annual", "annual", "multi_year" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cadence_value" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cadence_value" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cadence_value" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "start_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "start_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "start_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "auto_renew" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expected_end_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expected_end_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expected_end_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_billing_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_billing_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_billing_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "suspension_state" }, "type": { "const": "eq" }, "value": { "enum": [ "none", "medically_suspended", "operator_paused", "self_paused" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "suspension_started_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "suspension_started_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "suspension_started_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contract_terms_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contract_terms_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "cadence", "cadence_value", "start_date", "expected_end_date", "next_billing_date", "suspension_state", "suspension_started_at", "contract_terms_text" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership_subscription" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "Recurring amount per cycle", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Membership subscription amount", "type": "object" }, "auto_renew": { "title": "Auto-renew (autopay flag)", "type": "boolean" }, "cadence": { "enum": [ "monthly", "quarterly", "semi_annual", "annual", "multi_year" ], "title": "Billing cadence", "type": "string" }, "cadence_value": { "title": "Cadence value (for multi_year, the number of years; else 1)", "type": "integer" }, "contract_terms_text": { "title": "Contract-terms snapshot at signing (design-spec §B.2)", "type": "string" }, "currency": { "format": "iso-4217", "title": "Currency (ISO 4217)", "type": "string" }, "expected_end_date": { "format": "date", "title": "Expected end (null for open-ended autopay)", "type": "string" }, "id": { "title": "Subscription id", "type": "string" }, "next_billing_date": { "format": "date", "title": "Next scheduled charge date", "type": "string" }, "start_date": { "format": "date", "title": "Subscription start", "type": "string" }, "suspension_started_at": { "format": "date-time", "title": "When suspension started (required when suspension_state != none)", "type": "string" }, "suspension_state": { "enum": [ "none", "medically_suspended", "operator_paused", "self_paused" ], "title": "Suspension state (typed reason)", "type": "string" } }, "required": [ "id", "currency", "cadence", "cadence_value", "start_date", "auto_renew" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.membership_subscription:read" ] } ], "summary": "Search Membership subscription", "tags": [ "membership" ] } }, "/v1/object-types/hospitality.membership_tier/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA tier definition that admits Saint Haven (quota_ladder), Soho House Every House vs Local House (scope_set), RH Members (discount_bundle), and Aman Founders (recognition_band) without per-operator extension. The `tier_kind` enum is the load-bearing distinguisher; the shape-specific fields (`quota_size`, `prorates_on_change`, `transferable`, `legacy_initiation`) become meaningful only when the tier_kind calls for them.", "operationId": "get_hospitality_membership_tier", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership_tier" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Tier code", "type": "string" }, "description": { "title": "Description", "type": "string" }, "is_active": { "title": "Currently offered (sunset tiers coexist with active tiers)", "type": "boolean" }, "legacy_initiation": { "title": "Tier carries a non-recurring initiation fee (see commit 3 membership_initiation)", "type": "boolean" }, "name": { "title": "Tier name", "type": "string" }, "prorates_on_change": { "title": "Prorates dues on mid-cycle tier change", "type": "boolean" }, "proration_method": { "enum": [ "daily", "monthly", "none" ], "title": "Proration method (required when prorates_on_change = true)", "type": "string" }, "quota_remaining": { "title": "Quota remaining (denormalised projection)", "type": "integer" }, "quota_remaining_computed_at": { "format": "date-time", "title": "When quota_remaining was last computed", "type": "string" }, "quota_size": { "title": "Quota size (required when tier_kind = quota_ladder)", "type": "integer" }, "refund_policy_text": { "title": "Refund policy snapshot at tier creation (design-spec §B.2)", "type": "string" }, "tier_kind": { "enum": [ "quota_ladder", "scope_set", "discount_bundle", "recognition_band" ], "title": "Tier kind (load-bearing — see enum docs)", "type": "string" }, "transferable": { "title": "Tier survives original member's death / departure (Aman Founders legacy)", "type": "boolean" } }, "required": [ "code", "name", "tier_kind", "is_active", "prorates_on_change", "transferable", "legacy_initiation" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.membership_tier:read" ] } ], "summary": "Read Membership tier", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.membership_tier/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA tier definition that admits Saint Haven (quota_ladder), Soho House Every House vs Local House (scope_set), RH Members (discount_bundle), and Aman Founders (recognition_band) without per-operator extension. The `tier_kind` enum is the load-bearing distinguisher; the shape-specific fields (`quota_size`, `prorates_on_change`, `transferable`, `legacy_initiation`) become meaningful only when the tier_kind calls for them.", "operationId": "get_hospitality_membership_tier_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.membership_tier" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.membership_tier:read" ] } ], "summary": "Read Membership tier as of a watermark", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.membership_tier/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA tier definition that admits Saint Haven (quota_ladder), Soho House Every House vs Local House (scope_set), RH Members (discount_bundle), and Aman Founders (recognition_band) without per-operator extension. The `tier_kind` enum is the load-bearing distinguisher; the shape-specific fields (`quota_size`, `prorates_on_change`, `transferable`, `legacy_initiation`) become meaningful only when the tier_kind calls for them.", "operationId": "list_links_hospitality_membership_tier", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.membership_tier:read" ] } ], "summary": "List links of Membership tier", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.membership_at_tier" ] } } ] }, "/v1/object-types/hospitality.membership_tier/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA tier definition that admits Saint Haven (quota_ladder), Soho House Every House vs Local House (scope_set), RH Members (discount_bundle), and Aman Founders (recognition_band) without per-operator extension. The `tier_kind` enum is the load-bearing distinguisher; the shape-specific fields (`quota_size`, `prorates_on_change`, `transferable`, `legacy_initiation`) become meaningful only when the tier_kind calls for them.", "operationId": "traverse_hospitality_membership_tier", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.membership_at_tier" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.membership_tier:read" ] } ], "summary": "Traverse from Membership tier", "tags": [ "membership" ] } }, "/v1/object-types/hospitality.membership_tier/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA tier definition that admits Saint Haven (quota_ladder), Soho House Every House vs Local House (scope_set), RH Members (discount_bundle), and Aman Founders (recognition_band) without per-operator extension. The `tier_kind` enum is the load-bearing distinguisher; the shape-specific fields (`quota_size`, `prorates_on_change`, `transferable`, `legacy_initiation`) become meaningful only when the tier_kind calls for them.", "operationId": "search_hospitality_membership_tier", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tier_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "quota_ladder", "scope_set", "discount_bundle", "recognition_band" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "is_active" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quota_size" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quota_size" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quota_size" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quota_remaining" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quota_remaining" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quota_remaining" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quota_remaining_computed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quota_remaining_computed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quota_remaining_computed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "prorates_on_change" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "proration_method" }, "type": { "const": "eq" }, "value": { "enum": [ "daily", "monthly", "none" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "transferable" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "legacy_initiation" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refund_policy_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refund_policy_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "tier_kind", "description", "quota_size", "quota_remaining", "quota_remaining_computed_at", "proration_method", "refund_policy_text" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.membership_tier" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Tier code", "type": "string" }, "description": { "title": "Description", "type": "string" }, "is_active": { "title": "Currently offered (sunset tiers coexist with active tiers)", "type": "boolean" }, "legacy_initiation": { "title": "Tier carries a non-recurring initiation fee (see commit 3 membership_initiation)", "type": "boolean" }, "name": { "title": "Tier name", "type": "string" }, "prorates_on_change": { "title": "Prorates dues on mid-cycle tier change", "type": "boolean" }, "proration_method": { "enum": [ "daily", "monthly", "none" ], "title": "Proration method (required when prorates_on_change = true)", "type": "string" }, "quota_remaining": { "title": "Quota remaining (denormalised projection)", "type": "integer" }, "quota_remaining_computed_at": { "format": "date-time", "title": "When quota_remaining was last computed", "type": "string" }, "quota_size": { "title": "Quota size (required when tier_kind = quota_ladder)", "type": "integer" }, "refund_policy_text": { "title": "Refund policy snapshot at tier creation (design-spec §B.2)", "type": "string" }, "tier_kind": { "enum": [ "quota_ladder", "scope_set", "discount_bundle", "recognition_band" ], "title": "Tier kind (load-bearing — see enum docs)", "type": "string" }, "transferable": { "title": "Tier survives original member's death / departure (Aman Founders legacy)", "type": "boolean" } }, "required": [ "code", "name", "tier_kind", "is_active", "prorates_on_change", "transferable", "legacy_initiation" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.membership_tier:read" ] } ], "summary": "Search Membership tier", "tags": [ "membership" ] } }, "/v1/object-types/hospitality.menu/objects/{id}": { "get": { "description": "Read an existing instance.\n\nAn orderable menu attached to an outlet, with a daypart and a draft/active/retired lifecycle. Deliberately unversioned: check_line.unit_price snapshots the price at order time, so menu edits never rewrite financial history (proposal 0031 §Ratified design 2).", "operationId": "get_hospitality_menu", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.menu" }, "properties": { "additionalProperties": false, "properties": { "daypart": { "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "title": "When the menu runs", "type": "string" }, "id": { "title": "Menu id", "type": "string" }, "name": { "title": "Menu name", "type": "string" }, "status": { "enum": [ "draft", "active", "retired" ], "title": "Menu lifecycle status", "type": "string" } }, "required": [ "id", "name", "daypart", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.menu:read" ] } ], "summary": "Read Menu", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.menu/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nAn orderable menu attached to an outlet, with a daypart and a draft/active/retired lifecycle. Deliberately unversioned: check_line.unit_price snapshots the price at order time, so menu edits never rewrite financial history (proposal 0031 §Ratified design 2).", "operationId": "get_hospitality_menu_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.menu" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.menu:read" ] } ], "summary": "Read Menu as of a watermark", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.menu/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nAn orderable menu attached to an outlet, with a daypart and a draft/active/retired lifecycle. Deliberately unversioned: check_line.unit_price snapshots the price at order time, so menu edits never rewrite financial history (proposal 0031 §Ratified design 2).", "operationId": "list_links_hospitality_menu", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.menu:read" ] } ], "summary": "List links of Menu", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.menu_for_outlet", "hospitality.link.menu_section_of_menu" ] } } ] }, "/v1/object-types/hospitality.menu/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nAn orderable menu attached to an outlet, with a daypart and a draft/active/retired lifecycle. Deliberately unversioned: check_line.unit_price snapshots the price at order time, so menu edits never rewrite financial history (proposal 0031 §Ratified design 2).", "operationId": "traverse_hospitality_menu", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.menu_for_outlet", "hospitality.link.menu_section_of_menu" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.menu:read" ] } ], "summary": "Traverse from Menu", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.menu/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nAn orderable menu attached to an outlet, with a daypart and a draft/active/retired lifecycle. Deliberately unversioned: check_line.unit_price snapshots the price at order time, so menu edits never rewrite financial history (proposal 0031 §Ratified design 2).", "operationId": "search_hospitality_menu", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "daypart" }, "type": { "const": "eq" }, "value": { "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "draft", "active", "retired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "name", "daypart", "status" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.menu" }, "properties": { "additionalProperties": false, "properties": { "daypart": { "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "title": "When the menu runs", "type": "string" }, "id": { "title": "Menu id", "type": "string" }, "name": { "title": "Menu name", "type": "string" }, "status": { "enum": [ "draft", "active", "retired" ], "title": "Menu lifecycle status", "type": "string" } }, "required": [ "id", "name", "daypart", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.menu:read" ] } ], "summary": "Search Menu", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.menu_item/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe catalogue master of one dish or drink, shared by every outlet that sells it: names, its item class (menu_item_in_class → VAT, revenue category, course), the reporting group menu engineering reads, and its allergens. What gets priced and ordered is a menu_item_variant (variant_of_menu_item); where it appears is menu_item_in_section; an optional recipe binding (menu_item_uses_recipe) carries COGS. Distinct from service_item, the venue-level catalogue row.", "operationId": "get_hospitality_menu_item", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.menu_item" }, "properties": { "additionalProperties": false, "properties": { "active": { "title": "Orderable", "type": "boolean" }, "allergens": { "description": "The item's declared allergens (Food Information Regulations 2014). Absent = not yet declared, which the till treats as unknown; an empty list declares none. A recipe-bound item takes its recipe's rollup instead.", "items": { "enum": [ "gluten", "crustaceans", "eggs", "fish", "peanuts", "soybeans", "milk", "nuts", "celery", "mustard", "sesame", "sulphites", "lupin", "molluscs" ], "type": "string" }, "title": "Allergens (EU 14)", "type": "array" }, "code": { "title": "Item code", "type": "string" }, "course_default": { "title": "Course number override (else the class's)", "type": "integer" }, "description": { "title": "Guest-facing description", "type": "string" }, "name": { "title": "Item name", "type": "string" }, "orderable_alone": { "description": "False for an item that is only ever added as a modifier option (extra bacon, a side sauce) and so has no till key of its own.", "title": "Orderable on its own", "type": "boolean" }, "reporting_group": { "description": "The operator's own grouping for menu engineering and sales reports (Starters, Grills, Red wine) — Simphony's family group. The revenue split itself comes from the item class.", "title": "Reporting group", "type": "string" }, "short_name": { "description": "What a till key and a kitchen ticket show when the full name will not fit.", "title": "Short name", "type": "string" } }, "required": [ "code", "name", "orderable_alone", "active" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.menu_item:read" ] } ], "summary": "Read Menu item", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.menu_item/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe catalogue master of one dish or drink, shared by every outlet that sells it: names, its item class (menu_item_in_class → VAT, revenue category, course), the reporting group menu engineering reads, and its allergens. What gets priced and ordered is a menu_item_variant (variant_of_menu_item); where it appears is menu_item_in_section; an optional recipe binding (menu_item_uses_recipe) carries COGS. Distinct from service_item, the venue-level catalogue row.", "operationId": "get_hospitality_menu_item_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.menu_item" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.menu_item:read" ] } ], "summary": "Read Menu item as of a watermark", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.menu_item/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe catalogue master of one dish or drink, shared by every outlet that sells it: names, its item class (menu_item_in_class → VAT, revenue category, course), the reporting group menu engineering reads, and its allergens. What gets priced and ordered is a menu_item_variant (variant_of_menu_item); where it appears is menu_item_in_section; an optional recipe binding (menu_item_uses_recipe) carries COGS. Distinct from service_item, the venue-level catalogue row.", "operationId": "list_links_hospitality_menu_item", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.menu_item:read" ] } ], "summary": "List links of Menu item", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.check_line_for_menu_item", "hospitality.link.menu_item_in_class", "hospitality.link.menu_item_in_section", "hospitality.link.menu_item_prepared_at_station", "hospitality.link.menu_item_uses_modifier_group", "hospitality.link.menu_item_uses_recipe", "hospitality.link.variant_of_menu_item" ] } } ] }, "/v1/object-types/hospitality.menu_item/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe catalogue master of one dish or drink, shared by every outlet that sells it: names, its item class (menu_item_in_class → VAT, revenue category, course), the reporting group menu engineering reads, and its allergens. What gets priced and ordered is a menu_item_variant (variant_of_menu_item); where it appears is menu_item_in_section; an optional recipe binding (menu_item_uses_recipe) carries COGS. Distinct from service_item, the venue-level catalogue row.", "operationId": "traverse_hospitality_menu_item", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.check_line_for_menu_item", "hospitality.link.menu_item_in_class", "hospitality.link.menu_item_in_section", "hospitality.link.menu_item_prepared_at_station", "hospitality.link.menu_item_uses_modifier_group", "hospitality.link.menu_item_uses_recipe", "hospitality.link.variant_of_menu_item" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.menu_item:read" ] } ], "summary": "Traverse from Menu item", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.menu_item/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe catalogue master of one dish or drink, shared by every outlet that sells it: names, its item class (menu_item_in_class → VAT, revenue category, course), the reporting group menu engineering reads, and its allergens. What gets priced and ordered is a menu_item_variant (variant_of_menu_item); where it appears is menu_item_in_section; an optional recipe binding (menu_item_uses_recipe) carries COGS. Distinct from service_item, the venue-level catalogue row.", "operationId": "search_hospitality_menu_item", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "short_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "short_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "short_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "short_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reporting_group" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reporting_group" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reporting_group" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reporting_group" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "allergens" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "gluten", "crustaceans", "eggs", "fish", "peanuts", "soybeans", "milk", "nuts", "celery", "mustard", "sesame", "sulphites", "lupin", "molluscs" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "course_default" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "course_default" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "course_default" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "orderable_alone" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "active" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "short_name", "description", "reporting_group", "course_default" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.menu_item" }, "properties": { "additionalProperties": false, "properties": { "active": { "title": "Orderable", "type": "boolean" }, "allergens": { "description": "The item's declared allergens (Food Information Regulations 2014). Absent = not yet declared, which the till treats as unknown; an empty list declares none. A recipe-bound item takes its recipe's rollup instead.", "items": { "enum": [ "gluten", "crustaceans", "eggs", "fish", "peanuts", "soybeans", "milk", "nuts", "celery", "mustard", "sesame", "sulphites", "lupin", "molluscs" ], "type": "string" }, "title": "Allergens (EU 14)", "type": "array" }, "code": { "title": "Item code", "type": "string" }, "course_default": { "title": "Course number override (else the class's)", "type": "integer" }, "description": { "title": "Guest-facing description", "type": "string" }, "name": { "title": "Item name", "type": "string" }, "orderable_alone": { "description": "False for an item that is only ever added as a modifier option (extra bacon, a side sauce) and so has no till key of its own.", "title": "Orderable on its own", "type": "boolean" }, "reporting_group": { "description": "The operator's own grouping for menu engineering and sales reports (Starters, Grills, Red wine) — Simphony's family group. The revenue split itself comes from the item class.", "title": "Reporting group", "type": "string" }, "short_name": { "description": "What a till key and a kitchen ticket show when the full name will not fit.", "title": "Short name", "type": "string" } }, "required": [ "code", "name", "orderable_alone", "active" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.menu_item:read" ] } ], "summary": "Search Menu item", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.menu_item_variant/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe priced, orderable unit of a menu item — a 125 / 175 / 250 ml glass, a bottle, a half or full portion. Every item has at least one; a single-size item has one default variant. Prices attach here (price_for_variant), and a check line records the variant it sold.", "operationId": "get_hospitality_menu_item_variant", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.menu_item_variant" }, "properties": { "additionalProperties": false, "properties": { "active": { "title": "Orderable", "type": "boolean" }, "id": { "title": "Variant id", "type": "string" }, "is_default": { "description": "The variant a till key or a feed line naming only the item rings. An item with one variant uses it whatever this says.", "title": "Default variant", "type": "boolean" }, "measure": { "description": "The quantity served, as the menu states it (175 ml, 25 ml, 8 oz) — wine and spirits must be offered in specified quantities.", "title": "Measure", "type": "string" }, "name": { "title": "Variant name (Regular, 175 ml, Bottle)", "type": "string" }, "sort_order": { "title": "Order on the till", "type": "integer" } }, "required": [ "id", "name", "is_default", "active" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.menu_item_variant:read" ] } ], "summary": "Read Menu item variant", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.menu_item_variant/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe priced, orderable unit of a menu item — a 125 / 175 / 250 ml glass, a bottle, a half or full portion. Every item has at least one; a single-size item has one default variant. Prices attach here (price_for_variant), and a check line records the variant it sold.", "operationId": "get_hospitality_menu_item_variant_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.menu_item_variant" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.menu_item_variant:read" ] } ], "summary": "Read Menu item variant as of a watermark", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.menu_item_variant/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe priced, orderable unit of a menu item — a 125 / 175 / 250 ml glass, a bottle, a half or full portion. Every item has at least one; a single-size item has one default variant. Prices attach here (price_for_variant), and a check line records the variant it sold.", "operationId": "list_links_hospitality_menu_item_variant", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.menu_item_variant:read" ] } ], "summary": "List links of Menu item variant", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.check_line_for_variant", "hospitality.link.modifier_option_adds_variant", "hospitality.link.price_for_variant", "hospitality.link.variant_of_menu_item" ] } } ] }, "/v1/object-types/hospitality.menu_item_variant/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe priced, orderable unit of a menu item — a 125 / 175 / 250 ml glass, a bottle, a half or full portion. Every item has at least one; a single-size item has one default variant. Prices attach here (price_for_variant), and a check line records the variant it sold.", "operationId": "traverse_hospitality_menu_item_variant", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.check_line_for_variant", "hospitality.link.modifier_option_adds_variant", "hospitality.link.price_for_variant", "hospitality.link.variant_of_menu_item" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.menu_item_variant:read" ] } ], "summary": "Traverse from Menu item variant", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.menu_item_variant/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe priced, orderable unit of a menu item — a 125 / 175 / 250 ml glass, a bottle, a half or full portion. Every item has at least one; a single-size item has one default variant. Prices attach here (price_for_variant), and a check line records the variant it sold.", "operationId": "search_hospitality_menu_item_variant", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "measure" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "measure" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "measure" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "measure" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "is_default" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sort_order" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sort_order" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sort_order" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "active" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "name", "measure", "sort_order" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.menu_item_variant" }, "properties": { "additionalProperties": false, "properties": { "active": { "title": "Orderable", "type": "boolean" }, "id": { "title": "Variant id", "type": "string" }, "is_default": { "description": "The variant a till key or a feed line naming only the item rings. An item with one variant uses it whatever this says.", "title": "Default variant", "type": "boolean" }, "measure": { "description": "The quantity served, as the menu states it (175 ml, 25 ml, 8 oz) — wine and spirits must be offered in specified quantities.", "title": "Measure", "type": "string" }, "name": { "title": "Variant name (Regular, 175 ml, Bottle)", "type": "string" }, "sort_order": { "title": "Order on the till", "type": "integer" } }, "required": [ "id", "name", "is_default", "active" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.menu_item_variant:read" ] } ], "summary": "Search Menu item variant", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.menu_section/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA heading on a menu (Starters, Grills, Wine by the glass) — what the till screen's category keys and the printed menu group items by. Belongs to one menu (menu_section_of_menu); items join it through menu_item_in_section, so one item can sit on the breakfast menu and the room-service menu at once.", "operationId": "get_hospitality_menu_section", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.menu_section" }, "properties": { "additionalProperties": false, "properties": { "id": { "title": "Section id", "type": "string" }, "name": { "title": "Section name", "type": "string" }, "sort_order": { "title": "Order on the menu", "type": "integer" } }, "required": [ "id", "name" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.menu_section:read" ] } ], "summary": "Read Menu section", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.menu_section/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA heading on a menu (Starters, Grills, Wine by the glass) — what the till screen's category keys and the printed menu group items by. Belongs to one menu (menu_section_of_menu); items join it through menu_item_in_section, so one item can sit on the breakfast menu and the room-service menu at once.", "operationId": "get_hospitality_menu_section_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.menu_section" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.menu_section:read" ] } ], "summary": "Read Menu section as of a watermark", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.menu_section/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA heading on a menu (Starters, Grills, Wine by the glass) — what the till screen's category keys and the printed menu group items by. Belongs to one menu (menu_section_of_menu); items join it through menu_item_in_section, so one item can sit on the breakfast menu and the room-service menu at once.", "operationId": "list_links_hospitality_menu_section", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.menu_section:read" ] } ], "summary": "List links of Menu section", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.menu_item_in_section", "hospitality.link.menu_section_of_menu" ] } } ] }, "/v1/object-types/hospitality.menu_section/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA heading on a menu (Starters, Grills, Wine by the glass) — what the till screen's category keys and the printed menu group items by. Belongs to one menu (menu_section_of_menu); items join it through menu_item_in_section, so one item can sit on the breakfast menu and the room-service menu at once.", "operationId": "traverse_hospitality_menu_section", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.menu_item_in_section", "hospitality.link.menu_section_of_menu" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.menu_section:read" ] } ], "summary": "Traverse from Menu section", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.menu_section/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA heading on a menu (Starters, Grills, Wine by the glass) — what the till screen's category keys and the printed menu group items by. Belongs to one menu (menu_section_of_menu); items join it through menu_item_in_section, so one item can sit on the breakfast menu and the room-service menu at once.", "operationId": "search_hospitality_menu_section", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sort_order" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sort_order" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sort_order" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "name", "sort_order" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.menu_section" }, "properties": { "additionalProperties": false, "properties": { "id": { "title": "Section id", "type": "string" }, "name": { "title": "Section name", "type": "string" }, "sort_order": { "title": "Order on the menu", "type": "integer" } }, "required": [ "id", "name" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.menu_section:read" ] } ], "summary": "Search Menu section", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.merchant_account/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA property's own account at the payment processor, opened under the platform's (Stripe Connect). While one is `active`, the property's card payments settle to it — the hotel is the merchant the guest's statement names, its payouts go to its own bank — and the platform's fee is taken from each payment. A property with no open account takes card payments on the platform's own account. Verification is the processor's: the account is `onboarding` until the hotel has submitted its details, then `active` or `restricted` as the processor decides.", "operationId": "get_hospitality_merchant_account", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.merchant_account" }, "properties": { "additionalProperties": false, "properties": { "cards_exported_at": { "format": "date-time", "title": "When the platform operator last pulled this account's stored cards for the hotel's next processor (the Leaving policy's card export)", "type": "string" }, "cards_exported_count": { "title": "How many stored cards that export carried — the cards that name this account, are active and are on the processor", "type": "integer" }, "charges_enabled": { "title": "Whether the processor lets the account take card payments", "type": "boolean" }, "closed_at": { "format": "date-time", "title": "When the account was closed", "type": "string" }, "country": { "title": "Country the hotel trades in (ISO 3166-1 alpha-2) — fixed at opening, because the processor fixes it too", "type": "string" }, "details_submitted": { "title": "Whether the hotel has finished the processor's onboarding form", "type": "boolean" }, "disabled_reason": { "title": "The processor's reason the account cannot take charges, when it gives one", "type": "string" }, "external_account_disabled": { "title": "Whether the processor has disabled the bank account it pays out to (after a failed payout); no payout lands until the hotel replaces it", "type": "boolean" }, "external_account_disabled_ids": { "items": { "type": "string" }, "title": "The processor's ids of the default bank accounts it has disabled (`ba_…`, one per currency at most); `external_account_disabled` is whether there are any", "type": "array" }, "external_account_disabled_reason": { "title": "The processor's status for that bank account (`errored`, `verification_failed`) when it is disabled", "type": "string" }, "external_account_observed_at": { "format": "date-time", "title": "When the bank account's state was read — the watermark an out-of-order webhook is checked against", "type": "string" }, "fee_conversion_bps": { "title": "The processor's currency-conversion fee in basis points (Stripe: 2%), counted in the estimate of the processor's fee on a charge in a currency other than the schedule's", "type": "integer" }, "fee_schedule": { "description": "The platform's fee on each card payment settled to this account, by the card's class: one row for each of `domestic_standard`, `domestic_premium`, `regional` and `international`, online and card-present — the basis points and fixed fee the hotel pays (`bps`, `fixed`) beside the processor's own published rate for that class (`processor_bps`, `processor_fixed`), which is what the platform's estimate of the processor's fee uses. Taken when the money is captured, on the amount captured, rounded down. The fixed fees' currency is the schedule's: a charge in another currency carries no fixed fee.", "items": { "properties": { "bps": { "type": "integer" }, "card_present": { "type": "boolean" }, "fee_class": { "enum": [ "domestic_standard", "domestic_premium", "regional", "international" ], "type": "string" }, "fixed": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "processor_bps": { "type": "integer" }, "processor_fixed": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "fee_class", "card_present", "bps", "fixed", "processor_bps", "processor_fixed" ], "type": "object" }, "title": "Merchant account fee schedule", "type": "array" }, "id": { "title": "Merchant account id", "type": "string" }, "onboarding_link_expires_at": { "format": "date-time", "title": "When the hotel's current onboarding refresh link stops working", "type": "string" }, "onboarding_link_nonce_hash": { "title": "SHA-256 of the one-use secret in the hotel's current onboarding refresh link — the link that mints a fresh Stripe onboarding link without a sign-in", "type": "string" }, "opened_at": { "format": "date-time", "title": "When the account was opened", "type": "string" }, "payout_anchor": { "title": "The day a weekly payout goes (`monday` … `sunday`) or a monthly one (its day of the month, `1` … `31`); absent for daily and manual payouts", "type": "string" }, "payout_anchor_before": { "title": "The weekly or monthly anchor before the last change, if it had one", "type": "string" }, "payout_delay_days": { "title": "How many days the processor holds a payment before it can be paid out (Stripe's `delay_days`; calendar or business days by the account's country)", "type": "integer" }, "payout_delay_days_before": { "title": "The payout delay before the last change, if it had one", "type": "integer" }, "payout_interval": { "title": "How often the processor pays the balance out, in its own words (Stripe: `daily`, `weekly`, `monthly`, or `manual` — paid out only on request)", "type": "string" }, "payout_interval_before": { "title": "The payout interval before the last change, if it had one", "type": "string" }, "payout_schedule_changed_at": { "format": "date-time", "title": "When the processor last changed this account's payout schedule (the first schedule read is a report, not a change)", "type": "string" }, "payouts_enabled": { "title": "Whether the processor will pay the account's balance out to the hotel's bank", "type": "boolean" }, "provider": { "title": "Processor that holds the account (`stripe`)", "type": "string" }, "provider_account_ref": { "title": "The processor's id for the account (Stripe `acct_…`). An identifier, not a credential: nothing can be done with it without the platform's own key.", "type": "string" }, "rejected_at": { "format": "date-time", "title": "When the processor accepted the platform's rejection of a closed account — the end of its life there, which the processor admits only at a zero balance", "type": "string" }, "requirements_due": { "items": { "type": "string" }, "title": "What the processor still needs from the hotel, in its own vocabulary (`external_account`, `individual.verification.document`, …). Empty when nothing is owed.", "type": "array" }, "state_observed_at": { "format": "date-time", "title": "When the processor's view below was taken — the watermark an out-of-order webhook is checked against", "type": "string" }, "status": { "enum": [ "onboarding", "active", "restricted", "closed" ], "title": "Lifecycle status, derived from the processor's verification", "type": "string" } }, "required": [ "id", "status", "provider", "provider_account_ref", "country", "charges_enabled", "payouts_enabled", "details_submitted", "fee_schedule", "fee_conversion_bps", "opened_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.merchant_account:read" ] } ], "summary": "Read Merchant account", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.merchant_account/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA property's own account at the payment processor, opened under the platform's (Stripe Connect). While one is `active`, the property's card payments settle to it — the hotel is the merchant the guest's statement names, its payouts go to its own bank — and the platform's fee is taken from each payment. A property with no open account takes card payments on the platform's own account. Verification is the processor's: the account is `onboarding` until the hotel has submitted its details, then `active` or `restricted` as the processor decides.", "operationId": "get_hospitality_merchant_account_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.merchant_account" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.merchant_account:read" ] } ], "summary": "Read Merchant account as of a watermark", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.merchant_account/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA property's own account at the payment processor, opened under the platform's (Stripe Connect). While one is `active`, the property's card payments settle to it — the hotel is the merchant the guest's statement names, its payouts go to its own bank — and the platform's fee is taken from each payment. A property with no open account takes card payments on the platform's own account. Verification is the processor's: the account is `onboarding` until the hotel has submitted its details, then `active` or `restricted` as the processor decides.", "operationId": "list_links_hospitality_merchant_account", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.merchant_account:read" ] } ], "summary": "List links of Merchant account", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.merchant_account_for_property", "hospitality.link.payout_for_merchant_account", "hospitality.link.platform_ledger_line_for_merchant_account" ] } } ] }, "/v1/object-types/hospitality.merchant_account/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA property's own account at the payment processor, opened under the platform's (Stripe Connect). While one is `active`, the property's card payments settle to it — the hotel is the merchant the guest's statement names, its payouts go to its own bank — and the platform's fee is taken from each payment. A property with no open account takes card payments on the platform's own account. Verification is the processor's: the account is `onboarding` until the hotel has submitted its details, then `active` or `restricted` as the processor decides.", "operationId": "traverse_hospitality_merchant_account", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.merchant_account_for_property", "hospitality.link.payout_for_merchant_account", "hospitality.link.platform_ledger_line_for_merchant_account" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.merchant_account:read" ] } ], "summary": "Traverse from Merchant account", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.merchant_account/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA property's own account at the payment processor, opened under the platform's (Stripe Connect). While one is `active`, the property's card payments settle to it — the hotel is the merchant the guest's statement names, its payouts go to its own bank — and the platform's fee is taken from each payment. A property with no open account takes card payments on the platform's own account. Verification is the processor's: the account is `onboarding` until the hotel has submitted its details, then `active` or `restricted` as the processor decides.", "operationId": "search_hospitality_merchant_account", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "onboarding", "active", "restricted", "closed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider_account_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider_account_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider_account_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider_account_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "country" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "country" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "country" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "country" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "charges_enabled" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payouts_enabled" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "details_submitted" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requirements_due" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "disabled_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "disabled_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "disabled_reason" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "disabled_reason" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fee_schedule" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "bps": { "type": "integer" }, "card_present": { "type": "boolean" }, "fee_class": { "enum": [ "domestic_standard", "domestic_premium", "regional", "international" ], "type": "string" }, "fixed": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "processor_bps": { "type": "integer" }, "processor_fixed": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "fee_class", "card_present", "bps", "fixed", "processor_bps", "processor_fixed" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fee_conversion_bps" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fee_conversion_bps" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fee_conversion_bps" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "state_observed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "state_observed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "state_observed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_account_disabled" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_account_disabled_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_account_disabled_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_account_disabled_reason" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_account_disabled_reason" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_account_observed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_account_observed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_account_observed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_account_disabled_ids" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejected_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejected_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejected_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "onboarding_link_nonce_hash" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "onboarding_link_nonce_hash" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "onboarding_link_nonce_hash" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "onboarding_link_nonce_hash" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "onboarding_link_expires_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "onboarding_link_expires_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "onboarding_link_expires_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_interval" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_interval" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_interval" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_interval" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_delay_days" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_delay_days" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_delay_days" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_anchor" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_anchor" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_anchor" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_anchor" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_schedule_changed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_schedule_changed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_schedule_changed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_interval_before" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_interval_before" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_interval_before" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_interval_before" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_delay_days_before" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_delay_days_before" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_delay_days_before" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_anchor_before" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_anchor_before" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_anchor_before" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_anchor_before" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cards_exported_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cards_exported_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cards_exported_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cards_exported_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cards_exported_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cards_exported_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "status", "provider", "provider_account_ref", "country", "disabled_reason", "fee_conversion_bps", "opened_at", "state_observed_at", "closed_at", "external_account_disabled_reason", "external_account_observed_at", "rejected_at", "onboarding_link_nonce_hash", "onboarding_link_expires_at", "payout_interval", "payout_delay_days", "payout_anchor", "payout_schedule_changed_at", "payout_interval_before", "payout_delay_days_before", "payout_anchor_before", "cards_exported_at", "cards_exported_count" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.merchant_account" }, "properties": { "additionalProperties": false, "properties": { "cards_exported_at": { "format": "date-time", "title": "When the platform operator last pulled this account's stored cards for the hotel's next processor (the Leaving policy's card export)", "type": "string" }, "cards_exported_count": { "title": "How many stored cards that export carried — the cards that name this account, are active and are on the processor", "type": "integer" }, "charges_enabled": { "title": "Whether the processor lets the account take card payments", "type": "boolean" }, "closed_at": { "format": "date-time", "title": "When the account was closed", "type": "string" }, "country": { "title": "Country the hotel trades in (ISO 3166-1 alpha-2) — fixed at opening, because the processor fixes it too", "type": "string" }, "details_submitted": { "title": "Whether the hotel has finished the processor's onboarding form", "type": "boolean" }, "disabled_reason": { "title": "The processor's reason the account cannot take charges, when it gives one", "type": "string" }, "external_account_disabled": { "title": "Whether the processor has disabled the bank account it pays out to (after a failed payout); no payout lands until the hotel replaces it", "type": "boolean" }, "external_account_disabled_ids": { "items": { "type": "string" }, "title": "The processor's ids of the default bank accounts it has disabled (`ba_…`, one per currency at most); `external_account_disabled` is whether there are any", "type": "array" }, "external_account_disabled_reason": { "title": "The processor's status for that bank account (`errored`, `verification_failed`) when it is disabled", "type": "string" }, "external_account_observed_at": { "format": "date-time", "title": "When the bank account's state was read — the watermark an out-of-order webhook is checked against", "type": "string" }, "fee_conversion_bps": { "title": "The processor's currency-conversion fee in basis points (Stripe: 2%), counted in the estimate of the processor's fee on a charge in a currency other than the schedule's", "type": "integer" }, "fee_schedule": { "description": "The platform's fee on each card payment settled to this account, by the card's class: one row for each of `domestic_standard`, `domestic_premium`, `regional` and `international`, online and card-present — the basis points and fixed fee the hotel pays (`bps`, `fixed`) beside the processor's own published rate for that class (`processor_bps`, `processor_fixed`), which is what the platform's estimate of the processor's fee uses. Taken when the money is captured, on the amount captured, rounded down. The fixed fees' currency is the schedule's: a charge in another currency carries no fixed fee.", "items": { "properties": { "bps": { "type": "integer" }, "card_present": { "type": "boolean" }, "fee_class": { "enum": [ "domestic_standard", "domestic_premium", "regional", "international" ], "type": "string" }, "fixed": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "processor_bps": { "type": "integer" }, "processor_fixed": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "fee_class", "card_present", "bps", "fixed", "processor_bps", "processor_fixed" ], "type": "object" }, "title": "Merchant account fee schedule", "type": "array" }, "id": { "title": "Merchant account id", "type": "string" }, "onboarding_link_expires_at": { "format": "date-time", "title": "When the hotel's current onboarding refresh link stops working", "type": "string" }, "onboarding_link_nonce_hash": { "title": "SHA-256 of the one-use secret in the hotel's current onboarding refresh link — the link that mints a fresh Stripe onboarding link without a sign-in", "type": "string" }, "opened_at": { "format": "date-time", "title": "When the account was opened", "type": "string" }, "payout_anchor": { "title": "The day a weekly payout goes (`monday` … `sunday`) or a monthly one (its day of the month, `1` … `31`); absent for daily and manual payouts", "type": "string" }, "payout_anchor_before": { "title": "The weekly or monthly anchor before the last change, if it had one", "type": "string" }, "payout_delay_days": { "title": "How many days the processor holds a payment before it can be paid out (Stripe's `delay_days`; calendar or business days by the account's country)", "type": "integer" }, "payout_delay_days_before": { "title": "The payout delay before the last change, if it had one", "type": "integer" }, "payout_interval": { "title": "How often the processor pays the balance out, in its own words (Stripe: `daily`, `weekly`, `monthly`, or `manual` — paid out only on request)", "type": "string" }, "payout_interval_before": { "title": "The payout interval before the last change, if it had one", "type": "string" }, "payout_schedule_changed_at": { "format": "date-time", "title": "When the processor last changed this account's payout schedule (the first schedule read is a report, not a change)", "type": "string" }, "payouts_enabled": { "title": "Whether the processor will pay the account's balance out to the hotel's bank", "type": "boolean" }, "provider": { "title": "Processor that holds the account (`stripe`)", "type": "string" }, "provider_account_ref": { "title": "The processor's id for the account (Stripe `acct_…`). An identifier, not a credential: nothing can be done with it without the platform's own key.", "type": "string" }, "rejected_at": { "format": "date-time", "title": "When the processor accepted the platform's rejection of a closed account — the end of its life there, which the processor admits only at a zero balance", "type": "string" }, "requirements_due": { "items": { "type": "string" }, "title": "What the processor still needs from the hotel, in its own vocabulary (`external_account`, `individual.verification.document`, …). Empty when nothing is owed.", "type": "array" }, "state_observed_at": { "format": "date-time", "title": "When the processor's view below was taken — the watermark an out-of-order webhook is checked against", "type": "string" }, "status": { "enum": [ "onboarding", "active", "restricted", "closed" ], "title": "Lifecycle status, derived from the processor's verification", "type": "string" } }, "required": [ "id", "status", "provider", "provider_account_ref", "country", "charges_enabled", "payouts_enabled", "details_submitted", "fee_schedule", "fee_conversion_bps", "opened_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.merchant_account:read" ] } ], "summary": "Search Merchant account", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.message_triage/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA typed triage decision issued by an agent (or, less commonly, a human operator logging a manual triage into the audit trail) against a single inbound `guest_message`. Mostly-immutable post-issue: the intent / sentiment / urgency / factors / rationale / enrichment_snapshot are frozen at write time so the audit trail is the rationale at decision time, not against today's profile. The decision_* and chained_* fields mutate exactly once on the transition out of `suggested` (apply / reject / escalate / expire / supersede) — that single mutation is gated by the `decision_status_transitions` cross-link validator.", "operationId": "get_hospitality_message_triage", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.message_triage" }, "properties": { "additionalProperties": false, "properties": { "chained_action_correlation_id": { "title": "correlation_id of the chained action's ApplyActionResponse (set on `applied`)", "type": "string" }, "conversation_ref": { "format": "uuid", "title": "Denormalised conversation ref (for per-conversation triage queries)", "type": "string", "x-aerandil-references": "hospitality.guest_conversation" }, "decided_at": { "format": "date-time", "title": "When the triage transitioned out of suggested", "type": "string" }, "decided_by": { "title": "`principal.stable_id()` of the deciding principal", "type": "string" }, "decision_status": { "enum": [ "suggested", "applied", "rejected", "escalated", "expired", "superseded" ], "title": "Lifecycle state", "type": "string" }, "enrichment_snapshot": { "title": "Frozen context snapshot at issue time (§3.3.1; JSON; host populates)" }, "escalation_reason": { "enum": [ "low_confidence", "policy_block", "safety_keyword", "explicit_guest_request", "sensitive_topic", "ambiguity", "operator_override", "pci_disclosed", "phi_disclosed" ], "title": "Reason recorded on escalation", "type": "string" }, "expires_at": { "format": "date-time", "title": "After this, decision_status moves to expired", "type": "string" }, "factors_considered": { "items": { "enum": [ "message_text", "conversation_history", "guest_profile", "reservation_context", "recognition_history", "recovery_history", "loyalty_tier", "time_of_day", "language_detected", "attachment_present", "prior_triage_history", "safety_keywords", "other" ], "type": "string" }, "title": "Signals the classifier conditioned on", "type": "array" }, "id": { "title": "Triage id", "type": "string" }, "intent_alternatives": { "description": "Top-k alternative intents with scores (optional)", "items": { "properties": { "intent": { "enum": [ "booking.inquiry", "booking.modification", "booking.cancellation", "booking.confirmation_query", "complaint.cleanliness", "complaint.noise", "complaint.billing", "complaint.service", "complaint.food", "complaint.other", "service.amenities", "service.spa", "service.restaurant", "service.transport", "service.lost_and_found", "service.wake_up", "service.technical", "service.housekeeping", "service.in_room_dining", "service.other", "info.amenities", "info.directions", "info.payment_policy", "info.wifi", "info.hours", "info.other", "recognition.celebration", "safety.emergency", "marketing.feedback", "chitchat.general", "injection.suspected", "other.unclassified" ], "type": "string" }, "score": { "format": "decimal", "type": "string" } }, "required": [ "intent", "score" ], "type": "object" }, "title": "Message triage intent alternatives", "type": "array" }, "intent_confidence": { "enum": [ "low", "medium", "high" ], "title": "Operator-facing confidence ordinal", "type": "string" }, "intent_confidence_score": { "format": "decimal", "title": "Calibrated probability (0..=1) — set when the model emits one", "type": "string" }, "intent_primary": { "enum": [ "booking.inquiry", "booking.modification", "booking.cancellation", "booking.confirmation_query", "complaint.cleanliness", "complaint.noise", "complaint.billing", "complaint.service", "complaint.food", "complaint.other", "service.amenities", "service.spa", "service.restaurant", "service.transport", "service.lost_and_found", "service.wake_up", "service.technical", "service.housekeeping", "service.in_room_dining", "service.other", "info.amenities", "info.directions", "info.payment_policy", "info.wifi", "info.hours", "info.other", "recognition.celebration", "safety.emergency", "marketing.feedback", "chitchat.general", "injection.suspected", "other.unclassified" ], "title": "Leaf intent from MESSAGE_INTENTS (§3.3.2)", "type": "string" }, "issued_at": { "format": "date-time", "title": "When the agent emitted the triage", "type": "string" }, "message_ref": { "format": "uuid", "title": "The inbound `guest_message` this triage classifies", "type": "string", "x-aerandil-references": "hospitality.guest_message" }, "policy_outcomes": { "items": { "enum": [ "pan_redacted", "phi_redacted", "tcpa_opt_out_detected", "gdpr_erasure_referenced", "whatsapp_window_outside", "voice_consent_missing", "injection_attempt_detected", "safety_keyword_matched", "none" ], "type": "string" }, "title": "Compliance flags observed during triage", "type": "array" }, "rationale_text": { "title": "Human-readable explanation surfaced to operators", "type": "string" }, "recommended_action_kind": { "enum": [ "auto_respond", "chain_typed_action", "escalate_to_staff", "silent_acknowledge", "no_action" ], "title": "Discriminator for the apply path", "type": "string" }, "recommended_action_params": { "title": "Proposed parameters for the chained action (JSON object; validated at apply time)" }, "recommended_action_ref": { "title": "API name of the chained action (when kind = chain_typed_action)", "type": "string" }, "recommended_response_text": { "title": "Drafted reply text (when kind = auto_respond)", "type": "string" }, "rejection_reason": { "title": "Free-text reason on reject (gold-standard decision-log pattern)", "type": "string" }, "sentiment": { "enum": [ "negative", "neutral", "positive" ], "title": "Sentiment ordinal", "type": "string" }, "sentiment_score": { "format": "decimal", "title": "Calibrated sentiment score [-1.0, 1.0]", "type": "string" }, "urgency": { "enum": [ "low", "normal", "high", "critical" ], "title": "Urgency classification", "type": "string" } }, "required": [ "id", "message_ref", "conversation_ref", "intent_primary", "intent_confidence", "sentiment", "urgency", "factors_considered", "recommended_action_kind", "issued_at", "expires_at", "decision_status", "policy_outcomes" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.message_triage:read" ] } ], "summary": "Read Message triage", "tags": [ "messaging" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.message_triage/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA typed triage decision issued by an agent (or, less commonly, a human operator logging a manual triage into the audit trail) against a single inbound `guest_message`. Mostly-immutable post-issue: the intent / sentiment / urgency / factors / rationale / enrichment_snapshot are frozen at write time so the audit trail is the rationale at decision time, not against today's profile. The decision_* and chained_* fields mutate exactly once on the transition out of `suggested` (apply / reject / escalate / expire / supersede) — that single mutation is gated by the `decision_status_transitions` cross-link validator.", "operationId": "get_hospitality_message_triage_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.message_triage" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.message_triage:read" ] } ], "summary": "Read Message triage as of a watermark", "tags": [ "messaging" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.message_triage/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA typed triage decision issued by an agent (or, less commonly, a human operator logging a manual triage into the audit trail) against a single inbound `guest_message`. Mostly-immutable post-issue: the intent / sentiment / urgency / factors / rationale / enrichment_snapshot are frozen at write time so the audit trail is the rationale at decision time, not against today's profile. The decision_* and chained_* fields mutate exactly once on the transition out of `suggested` (apply / reject / escalate / expire / supersede) — that single mutation is gated by the `decision_status_transitions` cross-link validator.", "operationId": "list_links_hospitality_message_triage", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.message_triage:read" ] } ], "summary": "List links of Message triage", "tags": [ "messaging" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.fraud_assessment_for_prior_triage", "hospitality.link.housekeeping_task_from_triage", "hospitality.link.message_triage_at_property", "hospitality.link.message_triage_chained_action_target", "hospitality.link.message_triage_escalated_to_staff_member", "hospitality.link.message_triage_for_message", "hospitality.link.message_triage_superseded_by", "hospitality.link.pattern_clusters_message_triage", "hospitality.link.work_order_from_triage", "hospitality.link.workflow_run_targets_message_triage" ] } } ] }, "/v1/object-types/hospitality.message_triage/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA typed triage decision issued by an agent (or, less commonly, a human operator logging a manual triage into the audit trail) against a single inbound `guest_message`. Mostly-immutable post-issue: the intent / sentiment / urgency / factors / rationale / enrichment_snapshot are frozen at write time so the audit trail is the rationale at decision time, not against today's profile. The decision_* and chained_* fields mutate exactly once on the transition out of `suggested` (apply / reject / escalate / expire / supersede) — that single mutation is gated by the `decision_status_transitions` cross-link validator.", "operationId": "traverse_hospitality_message_triage", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.fraud_assessment_for_prior_triage", "hospitality.link.housekeeping_task_from_triage", "hospitality.link.message_triage_at_property", "hospitality.link.message_triage_chained_action_target", "hospitality.link.message_triage_escalated_to_staff_member", "hospitality.link.message_triage_for_message", "hospitality.link.message_triage_superseded_by", "hospitality.link.pattern_clusters_message_triage", "hospitality.link.work_order_from_triage", "hospitality.link.workflow_run_targets_message_triage" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.message_triage:read" ] } ], "summary": "Traverse from Message triage", "tags": [ "messaging" ] } }, "/v1/object-types/hospitality.message_triage/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA typed triage decision issued by an agent (or, less commonly, a human operator logging a manual triage into the audit trail) against a single inbound `guest_message`. Mostly-immutable post-issue: the intent / sentiment / urgency / factors / rationale / enrichment_snapshot are frozen at write time so the audit trail is the rationale at decision time, not against today's profile. The decision_* and chained_* fields mutate exactly once on the transition out of `suggested` (apply / reject / escalate / expire / supersede) — that single mutation is gated by the `decision_status_transitions` cross-link validator.", "operationId": "search_hospitality_message_triage", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "message_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.guest_message" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "conversation_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.guest_conversation" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "intent_primary" }, "type": { "const": "eq" }, "value": { "enum": [ "booking.inquiry", "booking.modification", "booking.cancellation", "booking.confirmation_query", "complaint.cleanliness", "complaint.noise", "complaint.billing", "complaint.service", "complaint.food", "complaint.other", "service.amenities", "service.spa", "service.restaurant", "service.transport", "service.lost_and_found", "service.wake_up", "service.technical", "service.housekeeping", "service.in_room_dining", "service.other", "info.amenities", "info.directions", "info.payment_policy", "info.wifi", "info.hours", "info.other", "recognition.celebration", "safety.emergency", "marketing.feedback", "chitchat.general", "injection.suspected", "other.unclassified" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "intent_alternatives" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "intent": { "enum": [ "booking.inquiry", "booking.modification", "booking.cancellation", "booking.confirmation_query", "complaint.cleanliness", "complaint.noise", "complaint.billing", "complaint.service", "complaint.food", "complaint.other", "service.amenities", "service.spa", "service.restaurant", "service.transport", "service.lost_and_found", "service.wake_up", "service.technical", "service.housekeeping", "service.in_room_dining", "service.other", "info.amenities", "info.directions", "info.payment_policy", "info.wifi", "info.hours", "info.other", "recognition.celebration", "safety.emergency", "marketing.feedback", "chitchat.general", "injection.suspected", "other.unclassified" ], "type": "string" }, "score": { "format": "decimal", "type": "string" } }, "required": [ "intent", "score" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "intent_confidence" }, "type": { "const": "eq" }, "value": { "enum": [ "low", "medium", "high" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "intent_confidence_score" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "intent_confidence_score" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "intent_confidence_score" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sentiment" }, "type": { "const": "eq" }, "value": { "enum": [ "negative", "neutral", "positive" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sentiment_score" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sentiment_score" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sentiment_score" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "urgency" }, "type": { "const": "eq" }, "value": { "enum": [ "low", "normal", "high", "critical" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "factors_considered" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "message_text", "conversation_history", "guest_profile", "reservation_context", "recognition_history", "recovery_history", "loyalty_tier", "time_of_day", "language_detected", "attachment_present", "prior_triage_history", "safety_keywords", "other" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_action_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "auto_respond", "chain_typed_action", "escalate_to_staff", "silent_acknowledge", "no_action" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_action_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_action_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_action_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_action_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_action_params" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_response_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_response_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rationale_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rationale_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "enrichment_snapshot" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decision_status" }, "type": { "const": "eq" }, "value": { "enum": [ "suggested", "applied", "rejected", "escalated", "expired", "superseded" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "chained_action_correlation_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "chained_action_correlation_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "chained_action_correlation_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "chained_action_correlation_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "escalation_reason" }, "type": { "const": "eq" }, "value": { "enum": [ "low_confidence", "policy_block", "safety_keyword", "explicit_guest_request", "sensitive_topic", "ambiguity", "operator_override", "pci_disclosed", "phi_disclosed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejection_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejection_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "policy_outcomes" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "pan_redacted", "phi_redacted", "tcpa_opt_out_detected", "gdpr_erasure_referenced", "whatsapp_window_outside", "voice_consent_missing", "injection_attempt_detected", "safety_keyword_matched", "none" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "intent_primary", "intent_confidence", "intent_confidence_score", "sentiment", "sentiment_score", "urgency", "recommended_action_kind", "recommended_action_ref", "recommended_response_text", "rationale_text", "issued_at", "expires_at", "decision_status", "decided_at", "decided_by", "chained_action_correlation_id", "escalation_reason", "rejection_reason" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.message_triage" }, "properties": { "additionalProperties": false, "properties": { "chained_action_correlation_id": { "title": "correlation_id of the chained action's ApplyActionResponse (set on `applied`)", "type": "string" }, "conversation_ref": { "format": "uuid", "title": "Denormalised conversation ref (for per-conversation triage queries)", "type": "string", "x-aerandil-references": "hospitality.guest_conversation" }, "decided_at": { "format": "date-time", "title": "When the triage transitioned out of suggested", "type": "string" }, "decided_by": { "title": "`principal.stable_id()` of the deciding principal", "type": "string" }, "decision_status": { "enum": [ "suggested", "applied", "rejected", "escalated", "expired", "superseded" ], "title": "Lifecycle state", "type": "string" }, "enrichment_snapshot": { "title": "Frozen context snapshot at issue time (§3.3.1; JSON; host populates)" }, "escalation_reason": { "enum": [ "low_confidence", "policy_block", "safety_keyword", "explicit_guest_request", "sensitive_topic", "ambiguity", "operator_override", "pci_disclosed", "phi_disclosed" ], "title": "Reason recorded on escalation", "type": "string" }, "expires_at": { "format": "date-time", "title": "After this, decision_status moves to expired", "type": "string" }, "factors_considered": { "items": { "enum": [ "message_text", "conversation_history", "guest_profile", "reservation_context", "recognition_history", "recovery_history", "loyalty_tier", "time_of_day", "language_detected", "attachment_present", "prior_triage_history", "safety_keywords", "other" ], "type": "string" }, "title": "Signals the classifier conditioned on", "type": "array" }, "id": { "title": "Triage id", "type": "string" }, "intent_alternatives": { "description": "Top-k alternative intents with scores (optional)", "items": { "properties": { "intent": { "enum": [ "booking.inquiry", "booking.modification", "booking.cancellation", "booking.confirmation_query", "complaint.cleanliness", "complaint.noise", "complaint.billing", "complaint.service", "complaint.food", "complaint.other", "service.amenities", "service.spa", "service.restaurant", "service.transport", "service.lost_and_found", "service.wake_up", "service.technical", "service.housekeeping", "service.in_room_dining", "service.other", "info.amenities", "info.directions", "info.payment_policy", "info.wifi", "info.hours", "info.other", "recognition.celebration", "safety.emergency", "marketing.feedback", "chitchat.general", "injection.suspected", "other.unclassified" ], "type": "string" }, "score": { "format": "decimal", "type": "string" } }, "required": [ "intent", "score" ], "type": "object" }, "title": "Message triage intent alternatives", "type": "array" }, "intent_confidence": { "enum": [ "low", "medium", "high" ], "title": "Operator-facing confidence ordinal", "type": "string" }, "intent_confidence_score": { "format": "decimal", "title": "Calibrated probability (0..=1) — set when the model emits one", "type": "string" }, "intent_primary": { "enum": [ "booking.inquiry", "booking.modification", "booking.cancellation", "booking.confirmation_query", "complaint.cleanliness", "complaint.noise", "complaint.billing", "complaint.service", "complaint.food", "complaint.other", "service.amenities", "service.spa", "service.restaurant", "service.transport", "service.lost_and_found", "service.wake_up", "service.technical", "service.housekeeping", "service.in_room_dining", "service.other", "info.amenities", "info.directions", "info.payment_policy", "info.wifi", "info.hours", "info.other", "recognition.celebration", "safety.emergency", "marketing.feedback", "chitchat.general", "injection.suspected", "other.unclassified" ], "title": "Leaf intent from MESSAGE_INTENTS (§3.3.2)", "type": "string" }, "issued_at": { "format": "date-time", "title": "When the agent emitted the triage", "type": "string" }, "message_ref": { "format": "uuid", "title": "The inbound `guest_message` this triage classifies", "type": "string", "x-aerandil-references": "hospitality.guest_message" }, "policy_outcomes": { "items": { "enum": [ "pan_redacted", "phi_redacted", "tcpa_opt_out_detected", "gdpr_erasure_referenced", "whatsapp_window_outside", "voice_consent_missing", "injection_attempt_detected", "safety_keyword_matched", "none" ], "type": "string" }, "title": "Compliance flags observed during triage", "type": "array" }, "rationale_text": { "title": "Human-readable explanation surfaced to operators", "type": "string" }, "recommended_action_kind": { "enum": [ "auto_respond", "chain_typed_action", "escalate_to_staff", "silent_acknowledge", "no_action" ], "title": "Discriminator for the apply path", "type": "string" }, "recommended_action_params": { "title": "Proposed parameters for the chained action (JSON object; validated at apply time)" }, "recommended_action_ref": { "title": "API name of the chained action (when kind = chain_typed_action)", "type": "string" }, "recommended_response_text": { "title": "Drafted reply text (when kind = auto_respond)", "type": "string" }, "rejection_reason": { "title": "Free-text reason on reject (gold-standard decision-log pattern)", "type": "string" }, "sentiment": { "enum": [ "negative", "neutral", "positive" ], "title": "Sentiment ordinal", "type": "string" }, "sentiment_score": { "format": "decimal", "title": "Calibrated sentiment score [-1.0, 1.0]", "type": "string" }, "urgency": { "enum": [ "low", "normal", "high", "critical" ], "title": "Urgency classification", "type": "string" } }, "required": [ "id", "message_ref", "conversation_ref", "intent_primary", "intent_confidence", "sentiment", "urgency", "factors_considered", "recommended_action_kind", "issued_at", "expires_at", "decision_status", "policy_outcomes" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.message_triage:read" ] } ], "summary": "Search Message triage", "tags": [ "messaging" ] } }, "/v1/object-types/hospitality.metric_definition/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA governed, versioned business-metric definition: the disambiguating prose (`description` / `formula_expression`) plus a structured reference list over registered object types and fields, so the definition cannot silently reference a field that doesn't exist. Versioned per `name` and superseded in place (prior versions live in the event history); `certify_metric` records operator sign-off, and a deprecated version only returns via `revise_metric` at a strictly greater version. The executable complement for kernel-conformed metrics lives in the MetricDef registry (`/v1/metrics/{name}`); this object is the certification layer NL-analytics and agents ground against.", "operationId": "get_hospitality_metric_definition", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.metric_definition" }, "properties": { "additionalProperties": false, "properties": { "authored_by": { "title": "Principal::stable_id() of the defining / revising principal", "type": "string" }, "certified_at": { "format": "date-time", "title": "When this version was certified (set by certify_metric)", "type": "string" }, "certified_by": { "title": "Principal::stable_id() of the certifying sign-off", "type": "string" }, "description": { "title": "Disambiguating prose — the definition operators sign off on", "type": "string" }, "display_name": { "title": "Display name", "type": "string" }, "formula_expression": { "title": "Canonical formula expression (governed prose, not executed)", "type": "string" }, "grain": { "enum": [ "property_day", "property_month", "venue_day", "venue_month", "outlet_day", "brand_month", "portfolio_month", "tenant_month" ], "title": "Organisational-unit × period grain the metric is defined over", "type": "string" }, "id": { "title": "Definition id", "type": "string" }, "name": { "title": "Metric name (snake_case; matches a registry metric when one exists)", "type": "string" }, "owner": { "title": "Accountable team / principal for the definition", "type": "string" }, "referenced_fields": { "items": { "type": "string" }, "title": "Registered `type.property` fields the formula reads", "type": "array" }, "referenced_object_types": { "items": { "type": "string" }, "title": "Registered object-type names the formula reads", "type": "array" }, "status": { "enum": [ "draft", "certified", "deprecated" ], "title": "Certification lifecycle status", "type": "string" }, "unit": { "enum": [ "money", "ratio", "percent", "count", "hours", "native_unit" ], "title": "Unit the metric's value carries", "type": "string" }, "version": { "title": "Monotonic version per name (revise_metric bumps it)", "type": "integer" } }, "required": [ "id", "name", "display_name", "description", "version", "status", "grain", "unit", "formula_expression", "referenced_object_types", "referenced_fields", "owner", "authored_by" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.metric_definition:read" ] } ], "summary": "Read Metric definition", "tags": [ "catalogue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.metric_definition/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA governed, versioned business-metric definition: the disambiguating prose (`description` / `formula_expression`) plus a structured reference list over registered object types and fields, so the definition cannot silently reference a field that doesn't exist. Versioned per `name` and superseded in place (prior versions live in the event history); `certify_metric` records operator sign-off, and a deprecated version only returns via `revise_metric` at a strictly greater version. The executable complement for kernel-conformed metrics lives in the MetricDef registry (`/v1/metrics/{name}`); this object is the certification layer NL-analytics and agents ground against.", "operationId": "get_hospitality_metric_definition_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.metric_definition" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.metric_definition:read" ] } ], "summary": "Read Metric definition as of a watermark", "tags": [ "catalogue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.metric_definition/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA governed, versioned business-metric definition: the disambiguating prose (`description` / `formula_expression`) plus a structured reference list over registered object types and fields, so the definition cannot silently reference a field that doesn't exist. Versioned per `name` and superseded in place (prior versions live in the event history); `certify_metric` records operator sign-off, and a deprecated version only returns via `revise_metric` at a strictly greater version. The executable complement for kernel-conformed metrics lives in the MetricDef registry (`/v1/metrics/{name}`); this object is the certification layer NL-analytics and agents ground against.", "operationId": "search_hospitality_metric_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "display_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "version" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "version" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "version" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "draft", "certified", "deprecated" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "grain" }, "type": { "const": "eq" }, "value": { "enum": [ "property_day", "property_month", "venue_day", "venue_month", "outlet_day", "brand_month", "portfolio_month", "tenant_month" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "unit" }, "type": { "const": "eq" }, "value": { "enum": [ "money", "ratio", "percent", "count", "hours", "native_unit" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "formula_expression" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "formula_expression" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "referenced_object_types" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "referenced_fields" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "owner" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "owner" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "owner" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "owner" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authored_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authored_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authored_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authored_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "certified_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "certified_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "certified_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "certified_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "certified_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "certified_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "certified_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "name", "display_name", "description", "version", "status", "grain", "unit", "formula_expression", "owner", "authored_by", "certified_at", "certified_by" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.metric_definition" }, "properties": { "additionalProperties": false, "properties": { "authored_by": { "title": "Principal::stable_id() of the defining / revising principal", "type": "string" }, "certified_at": { "format": "date-time", "title": "When this version was certified (set by certify_metric)", "type": "string" }, "certified_by": { "title": "Principal::stable_id() of the certifying sign-off", "type": "string" }, "description": { "title": "Disambiguating prose — the definition operators sign off on", "type": "string" }, "display_name": { "title": "Display name", "type": "string" }, "formula_expression": { "title": "Canonical formula expression (governed prose, not executed)", "type": "string" }, "grain": { "enum": [ "property_day", "property_month", "venue_day", "venue_month", "outlet_day", "brand_month", "portfolio_month", "tenant_month" ], "title": "Organisational-unit × period grain the metric is defined over", "type": "string" }, "id": { "title": "Definition id", "type": "string" }, "name": { "title": "Metric name (snake_case; matches a registry metric when one exists)", "type": "string" }, "owner": { "title": "Accountable team / principal for the definition", "type": "string" }, "referenced_fields": { "items": { "type": "string" }, "title": "Registered `type.property` fields the formula reads", "type": "array" }, "referenced_object_types": { "items": { "type": "string" }, "title": "Registered object-type names the formula reads", "type": "array" }, "status": { "enum": [ "draft", "certified", "deprecated" ], "title": "Certification lifecycle status", "type": "string" }, "unit": { "enum": [ "money", "ratio", "percent", "count", "hours", "native_unit" ], "title": "Unit the metric's value carries", "type": "string" }, "version": { "title": "Monotonic version per name (revise_metric bumps it)", "type": "integer" } }, "required": [ "id", "name", "display_name", "description", "version", "status", "grain", "unit", "formula_expression", "referenced_object_types", "referenced_fields", "owner", "authored_by" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.metric_definition:read" ] } ], "summary": "Search Metric definition", "tags": [ "catalogue" ] } }, "/v1/object-types/hospitality.modifier_group/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA choice an item asks for — How cooked, Choose a side, Add extras, or a set menu's Choose your main. Items attach groups through menu_item_uses_modifier_group (which may override the group's bounds for that item); options belong to it through modifier_option_in_group.", "operationId": "get_hospitality_modifier_group", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.modifier_group" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Group code", "type": "string" }, "max_select": { "title": "Most options the guest may choose (absent = no limit)", "type": "integer" }, "min_select": { "title": "Least options the guest must choose", "type": "integer" }, "name": { "title": "Group name", "type": "string" } }, "required": [ "code", "name", "min_select" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.modifier_group:read" ] } ], "summary": "Read Modifier group", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.modifier_group/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA choice an item asks for — How cooked, Choose a side, Add extras, or a set menu's Choose your main. Items attach groups through menu_item_uses_modifier_group (which may override the group's bounds for that item); options belong to it through modifier_option_in_group.", "operationId": "get_hospitality_modifier_group_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.modifier_group" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.modifier_group:read" ] } ], "summary": "Read Modifier group as of a watermark", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.modifier_group/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA choice an item asks for — How cooked, Choose a side, Add extras, or a set menu's Choose your main. Items attach groups through menu_item_uses_modifier_group (which may override the group's bounds for that item); options belong to it through modifier_option_in_group.", "operationId": "list_links_hospitality_modifier_group", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.modifier_group:read" ] } ], "summary": "List links of Modifier group", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.menu_item_uses_modifier_group", "hospitality.link.modifier_option_in_group" ] } } ] }, "/v1/object-types/hospitality.modifier_group/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA choice an item asks for — How cooked, Choose a side, Add extras, or a set menu's Choose your main. Items attach groups through menu_item_uses_modifier_group (which may override the group's bounds for that item); options belong to it through modifier_option_in_group.", "operationId": "traverse_hospitality_modifier_group", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.menu_item_uses_modifier_group", "hospitality.link.modifier_option_in_group" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.modifier_group:read" ] } ], "summary": "Traverse from Modifier group", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.modifier_group/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA choice an item asks for — How cooked, Choose a side, Add extras, or a set menu's Choose your main. Items attach groups through menu_item_uses_modifier_group (which may override the group's bounds for that item); options belong to it through modifier_option_in_group.", "operationId": "search_hospitality_modifier_group", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "min_select" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "min_select" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "min_select" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_select" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_select" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_select" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "min_select", "max_select" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.modifier_group" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Group code", "type": "string" }, "max_select": { "title": "Most options the guest may choose (absent = no limit)", "type": "integer" }, "min_select": { "title": "Least options the guest must choose", "type": "integer" }, "name": { "title": "Group name", "type": "string" } }, "required": [ "code", "name", "min_select" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.modifier_group:read" ] } ], "summary": "Search Modifier group", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.modifier_option/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne choice inside a modifier group. When it adds something sellable it points at that variant (modifier_option_adds_variant) and is priced at `price` if set, else at the variant's own price; with no variant it is an instruction to the kitchen (medium rare, no ice) and costs nothing.", "operationId": "get_hospitality_modifier_option", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.modifier_option" }, "properties": { "additionalProperties": false, "properties": { "id": { "title": "Option id", "type": "string" }, "is_default": { "title": "Chosen by default", "type": "boolean" }, "name": { "title": "Option name", "type": "string" }, "price": { "description": "What the option adds when chosen, if different from the variant's own price — a side of fries is £4.50, fries instead of salad £0, a set menu's steak supplement £8.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Modifier option price", "type": "object" }, "sort_order": { "title": "Order within the group", "type": "integer" } }, "required": [ "id", "name", "is_default" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.modifier_option:read" ] } ], "summary": "Read Modifier option", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.modifier_option/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne choice inside a modifier group. When it adds something sellable it points at that variant (modifier_option_adds_variant) and is priced at `price` if set, else at the variant's own price; with no variant it is an instruction to the kitchen (medium rare, no ice) and costs nothing.", "operationId": "get_hospitality_modifier_option_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.modifier_option" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.modifier_option:read" ] } ], "summary": "Read Modifier option as of a watermark", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.modifier_option/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne choice inside a modifier group. When it adds something sellable it points at that variant (modifier_option_adds_variant) and is priced at `price` if set, else at the variant's own price; with no variant it is an instruction to the kitchen (medium rare, no ice) and costs nothing.", "operationId": "list_links_hospitality_modifier_option", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.modifier_option:read" ] } ], "summary": "List links of Modifier option", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.modifier_option_adds_variant", "hospitality.link.modifier_option_in_group" ] } } ] }, "/v1/object-types/hospitality.modifier_option/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne choice inside a modifier group. When it adds something sellable it points at that variant (modifier_option_adds_variant) and is priced at `price` if set, else at the variant's own price; with no variant it is an instruction to the kitchen (medium rare, no ice) and costs nothing.", "operationId": "traverse_hospitality_modifier_option", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.modifier_option_adds_variant", "hospitality.link.modifier_option_in_group" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.modifier_option:read" ] } ], "summary": "Traverse from Modifier option", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.modifier_option/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne choice inside a modifier group. When it adds something sellable it points at that variant (modifier_option_adds_variant) and is priced at `price` if set, else at the variant's own price; with no variant it is an instruction to the kitchen (medium rare, no ice) and costs nothing.", "operationId": "search_hospitality_modifier_option", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "price" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "is_default" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sort_order" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sort_order" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sort_order" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "name", "sort_order" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.modifier_option" }, "properties": { "additionalProperties": false, "properties": { "id": { "title": "Option id", "type": "string" }, "is_default": { "title": "Chosen by default", "type": "boolean" }, "name": { "title": "Option name", "type": "string" }, "price": { "description": "What the option adds when chosen, if different from the variant's own price — a side of fries is £4.50, fries instead of salad £0, a set menu's steak supplement £8.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Modifier option price", "type": "object" }, "sort_order": { "title": "Order within the group", "type": "integer" } }, "required": [ "id", "name", "is_default" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.modifier_option:read" ] } ], "summary": "Search Modifier option", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.night_audit_run/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA single execution of the night audit cycle for one business date. Results are immutable on completion; re-runs create a new `NightAuditRun`. The status enum tracks lifecycle so a stuck or partial run is visible.", "operationId": "get_hospitality_night_audit_run", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.night_audit_run" }, "properties": { "additionalProperties": false, "properties": { "block_rooms_released": { "title": "Group-block room-nights the cutoff sweep returned to the house", "type": "integer" }, "business_date": { "format": "date", "title": "Business date", "type": "string" }, "commission_details_accrued": { "title": "Commission rows the run accrued on stays that completed", "type": "integer" }, "completed_at": { "format": "date-time", "title": "Completed at", "type": "string" }, "deposit_lapse_cancellations": { "title": "Lapsed unpaid deposits the sweep auto-cancelled per policy", "type": "integer" }, "deposit_lapses_flagged": { "title": "Deposit lapses recorded for operator disposition", "type": "integer" }, "exception_count": { "title": "Exception count", "type": "integer" }, "holds_released": { "title": "Expired courtesy holds the deposit sweep cancelled", "type": "integer" }, "id": { "title": "Run id", "type": "string" }, "open_cashier_sessions": { "title": "Cashier sessions still open at the close (exception, never a gate)", "type": "integer" }, "package_adjustments_posted": { "title": "Unconsumed package allowances the run settled as profit", "type": "integer" }, "payment_cards_expired": { "title": "Cards on file the run marked `expired` — active cards whose expiry month ended before the audited date", "type": "integer" }, "payment_requests_expired": { "title": "Payment requests the run expired — pending requests whose `expires_at` fell on or before the audited date (absent when none)", "type": "integer" }, "posted_room_revenue": { "description": "Posted room revenue", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Night audit run posted room revenue", "type": "object" }, "posted_room_tax": { "description": "Tax the run derived and posted alongside the room charges (inclusive and exclusive lines alike); absent when the posting spanned currencies", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Night audit run posted room tax", "type": "object" }, "started_at": { "format": "date-time", "title": "Started at", "type": "string" }, "status": { "enum": [ "in_progress", "completed", "failed", "rolled_back" ], "title": "Status", "type": "string" }, "visitor_keys_stripped": { "title": "Visitor keys the run stripped from offers, turnaways and reservations whose arrival night was past the property's grace", "type": "integer" }, "waitlist_entries_expired": { "title": "Waitlist entries the run aged out (departure + 2 business days)", "type": "integer" } }, "required": [ "id", "business_date", "started_at", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.night_audit_run:read" ] } ], "summary": "Read Night audit run", "tags": [ "audit" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.night_audit_run/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA single execution of the night audit cycle for one business date. Results are immutable on completion; re-runs create a new `NightAuditRun`. The status enum tracks lifecycle so a stuck or partial run is visible.", "operationId": "get_hospitality_night_audit_run_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.night_audit_run" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.night_audit_run:read" ] } ], "summary": "Read Night audit run as of a watermark", "tags": [ "audit" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.night_audit_run/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA single execution of the night audit cycle for one business date. Results are immutable on completion; re-runs create a new `NightAuditRun`. The status enum tracks lifecycle so a stuck or partial run is visible.", "operationId": "list_links_hospitality_night_audit_run", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.night_audit_run:read" ] } ], "summary": "List links of Night audit run", "tags": [ "audit" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.night_audit_run_for_business_date", "hospitality.link.property_has_night_audit_run" ] } } ] }, "/v1/object-types/hospitality.night_audit_run/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA single execution of the night audit cycle for one business date. Results are immutable on completion; re-runs create a new `NightAuditRun`. The status enum tracks lifecycle so a stuck or partial run is visible.", "operationId": "traverse_hospitality_night_audit_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.night_audit_run_for_business_date", "hospitality.link.property_has_night_audit_run" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.night_audit_run:read" ] } ], "summary": "Traverse from Night audit run", "tags": [ "audit" ] } }, "/v1/object-types/hospitality.night_audit_run/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA single execution of the night audit cycle for one business date. Results are immutable on completion; re-runs create a new `NightAuditRun`. The status enum tracks lifecycle so a stuck or partial run is visible.", "operationId": "search_hospitality_night_audit_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "in_progress", "completed", "failed", "rolled_back" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "posted_room_revenue" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "posted_room_tax" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "package_adjustments_posted" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "package_adjustments_posted" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "package_adjustments_posted" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "holds_released" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "holds_released" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "holds_released" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "deposit_lapse_cancellations" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "deposit_lapse_cancellations" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "deposit_lapse_cancellations" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "deposit_lapses_flagged" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "deposit_lapses_flagged" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "deposit_lapses_flagged" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "block_rooms_released" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "block_rooms_released" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "block_rooms_released" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commission_details_accrued" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commission_details_accrued" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "commission_details_accrued" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waitlist_entries_expired" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waitlist_entries_expired" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waitlist_entries_expired" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "visitor_keys_stripped" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "visitor_keys_stripped" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "visitor_keys_stripped" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_cards_expired" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_cards_expired" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_cards_expired" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_requests_expired" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_requests_expired" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_requests_expired" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "open_cashier_sessions" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "open_cashier_sessions" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "open_cashier_sessions" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "exception_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "exception_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "exception_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "business_date", "started_at", "completed_at", "status", "package_adjustments_posted", "holds_released", "deposit_lapse_cancellations", "deposit_lapses_flagged", "block_rooms_released", "commission_details_accrued", "waitlist_entries_expired", "visitor_keys_stripped", "payment_cards_expired", "payment_requests_expired", "open_cashier_sessions", "exception_count" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.night_audit_run" }, "properties": { "additionalProperties": false, "properties": { "block_rooms_released": { "title": "Group-block room-nights the cutoff sweep returned to the house", "type": "integer" }, "business_date": { "format": "date", "title": "Business date", "type": "string" }, "commission_details_accrued": { "title": "Commission rows the run accrued on stays that completed", "type": "integer" }, "completed_at": { "format": "date-time", "title": "Completed at", "type": "string" }, "deposit_lapse_cancellations": { "title": "Lapsed unpaid deposits the sweep auto-cancelled per policy", "type": "integer" }, "deposit_lapses_flagged": { "title": "Deposit lapses recorded for operator disposition", "type": "integer" }, "exception_count": { "title": "Exception count", "type": "integer" }, "holds_released": { "title": "Expired courtesy holds the deposit sweep cancelled", "type": "integer" }, "id": { "title": "Run id", "type": "string" }, "open_cashier_sessions": { "title": "Cashier sessions still open at the close (exception, never a gate)", "type": "integer" }, "package_adjustments_posted": { "title": "Unconsumed package allowances the run settled as profit", "type": "integer" }, "payment_cards_expired": { "title": "Cards on file the run marked `expired` — active cards whose expiry month ended before the audited date", "type": "integer" }, "payment_requests_expired": { "title": "Payment requests the run expired — pending requests whose `expires_at` fell on or before the audited date (absent when none)", "type": "integer" }, "posted_room_revenue": { "description": "Posted room revenue", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Night audit run posted room revenue", "type": "object" }, "posted_room_tax": { "description": "Tax the run derived and posted alongside the room charges (inclusive and exclusive lines alike); absent when the posting spanned currencies", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Night audit run posted room tax", "type": "object" }, "started_at": { "format": "date-time", "title": "Started at", "type": "string" }, "status": { "enum": [ "in_progress", "completed", "failed", "rolled_back" ], "title": "Status", "type": "string" }, "visitor_keys_stripped": { "title": "Visitor keys the run stripped from offers, turnaways and reservations whose arrival night was past the property's grace", "type": "integer" }, "waitlist_entries_expired": { "title": "Waitlist entries the run aged out (departure + 2 business days)", "type": "integer" } }, "required": [ "id", "business_date", "started_at", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.night_audit_run:read" ] } ], "summary": "Search Night audit run", "tags": [ "audit" ] } }, "/v1/object-types/hospitality.no_show_posting_rule/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne property's no-show posting rule for one reservation guarantee (OPERA's Post Revenue To No Shows): when the night audit marks a booking of that guarantee a no-show, it posts `all_nights` (every booked night's rate, as booked), `first_night` (the first night of every room), `deposit_only` (forfeits the deposit the house holds, nothing when it holds none) or `none`. Postings land on the booking's own account through the posting verbs, attributed to the rule's `outlet_id`; a deposit already on that account offsets them. A rule with no guarantee is the house default for every guarantee without a rule of its own; a house with no rule posts nothing. A booking a rule covers is posted by the rule alone — the frozen cancellation-policy fee step (`post_no_show_fees`) skips it, so one no-show is posted once.", "operationId": "get_hospitality_no_show_posting_rule", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.no_show_posting_rule" }, "properties": { "additionalProperties": false, "properties": { "active": { "title": "Whether the night audit applies this rule", "type": "boolean" }, "basis": { "enum": [ "all_nights", "first_night", "deposit_only", "none" ], "title": "What the audit posts for a no-show this rule covers", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "guarantee": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "title": "The reservation guarantee this rule is for; absent = the house default for any guarantee without a rule of its own", "type": "string" }, "id": { "title": "No-show posting rule id", "type": "string" }, "outlet_id": { "format": "uuid", "title": "The outlet every posting is attributed to (OPERA's single no-show posting transaction code); required unless the basis is `none`", "type": "string", "x-aerandil-references": "hospitality.outlet" } }, "required": [ "id", "basis", "active" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.no_show_posting_rule:read" ] } ], "summary": "Read No-show posting rule", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.no_show_posting_rule/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne property's no-show posting rule for one reservation guarantee (OPERA's Post Revenue To No Shows): when the night audit marks a booking of that guarantee a no-show, it posts `all_nights` (every booked night's rate, as booked), `first_night` (the first night of every room), `deposit_only` (forfeits the deposit the house holds, nothing when it holds none) or `none`. Postings land on the booking's own account through the posting verbs, attributed to the rule's `outlet_id`; a deposit already on that account offsets them. A rule with no guarantee is the house default for every guarantee without a rule of its own; a house with no rule posts nothing. A booking a rule covers is posted by the rule alone — the frozen cancellation-policy fee step (`post_no_show_fees`) skips it, so one no-show is posted once.", "operationId": "get_hospitality_no_show_posting_rule_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.no_show_posting_rule" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.no_show_posting_rule:read" ] } ], "summary": "Read No-show posting rule as of a watermark", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.no_show_posting_rule/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne property's no-show posting rule for one reservation guarantee (OPERA's Post Revenue To No Shows): when the night audit marks a booking of that guarantee a no-show, it posts `all_nights` (every booked night's rate, as booked), `first_night` (the first night of every room), `deposit_only` (forfeits the deposit the house holds, nothing when it holds none) or `none`. Postings land on the booking's own account through the posting verbs, attributed to the rule's `outlet_id`; a deposit already on that account offsets them. A rule with no guarantee is the house default for every guarantee without a rule of its own; a house with no rule posts nothing. A booking a rule covers is posted by the rule alone — the frozen cancellation-policy fee step (`post_no_show_fees`) skips it, so one no-show is posted once.", "operationId": "list_links_hospitality_no_show_posting_rule", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.no_show_posting_rule:read" ] } ], "summary": "List links of No-show posting rule", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.no_show_posting_rule_at_property" ] } } ] }, "/v1/object-types/hospitality.no_show_posting_rule/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne property's no-show posting rule for one reservation guarantee (OPERA's Post Revenue To No Shows): when the night audit marks a booking of that guarantee a no-show, it posts `all_nights` (every booked night's rate, as booked), `first_night` (the first night of every room), `deposit_only` (forfeits the deposit the house holds, nothing when it holds none) or `none`. Postings land on the booking's own account through the posting verbs, attributed to the rule's `outlet_id`; a deposit already on that account offsets them. A rule with no guarantee is the house default for every guarantee without a rule of its own; a house with no rule posts nothing. A booking a rule covers is posted by the rule alone — the frozen cancellation-policy fee step (`post_no_show_fees`) skips it, so one no-show is posted once.", "operationId": "traverse_hospitality_no_show_posting_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.no_show_posting_rule_at_property" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.no_show_posting_rule:read" ] } ], "summary": "Traverse from No-show posting rule", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.no_show_posting_rule/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne property's no-show posting rule for one reservation guarantee (OPERA's Post Revenue To No Shows): when the night audit marks a booking of that guarantee a no-show, it posts `all_nights` (every booked night's rate, as booked), `first_night` (the first night of every room), `deposit_only` (forfeits the deposit the house holds, nothing when it holds none) or `none`. Postings land on the booking's own account through the posting verbs, attributed to the rule's `outlet_id`; a deposit already on that account offsets them. A rule with no guarantee is the house default for every guarantee without a rule of its own; a house with no rule posts nothing. A booking a rule covers is posted by the rule alone — the frozen cancellation-policy fee step (`post_no_show_fees`) skips it, so one no-show is posted once.", "operationId": "search_hospitality_no_show_posting_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "guarantee" }, "type": { "const": "eq" }, "value": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "basis" }, "type": { "const": "eq" }, "value": { "enum": [ "all_nights", "first_night", "deposit_only", "none" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "outlet_id" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.outlet" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "active" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "guarantee", "basis", "description" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.no_show_posting_rule" }, "properties": { "additionalProperties": false, "properties": { "active": { "title": "Whether the night audit applies this rule", "type": "boolean" }, "basis": { "enum": [ "all_nights", "first_night", "deposit_only", "none" ], "title": "What the audit posts for a no-show this rule covers", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "guarantee": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "title": "The reservation guarantee this rule is for; absent = the house default for any guarantee without a rule of its own", "type": "string" }, "id": { "title": "No-show posting rule id", "type": "string" }, "outlet_id": { "format": "uuid", "title": "The outlet every posting is attributed to (OPERA's single no-show posting transaction code); required unless the basis is `none`", "type": "string", "x-aerandil-references": "hospitality.outlet" } }, "required": [ "id", "basis", "active" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.no_show_posting_rule:read" ] } ], "summary": "Search No-show posting rule", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.outlet/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA USALI-conformant revenue-bearing unit. Distinct from `venue` (the physical space) because outlets are revenue-reporting categories: the rooms outlet has no venue; a banquets-and-restaurant venue can host two revenue centers (one outlet each). `usali_department` is the chart-of-accounts classification; `kind` is the operational classification — orthogonal axes, since an outlet's accounting schedule and its operational shape do not always coincide (a third-party-licensed restaurant books as `other_operated` but operates as `restaurant`).", "operationId": "get_hospitality_outlet", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.outlet" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Outlet code", "type": "string" }, "description": { "title": "Description", "type": "string" }, "kind": { "enum": [ "rooms", "restaurant", "bar", "lounge", "room_service", "banquet", "catering", "spa", "salon", "wellness_program", "gym", "pool", "golf", "parking", "minibar", "retail", "activity", "tour", "rental", "business_center", "laundry", "telecom", "package_aggregator", "other" ], "title": "Operational kind", "type": "string" }, "meal_periods": { "description": "The outlet's meal periods (Simphony's serving periods, Toast's services): each a `daypart`, 24-hour `start_time` and `end_time` on the house's wall clock, and its `days_of_week`. `open_check` stamps a live check with the one in force. Written by `set_outlet_meal_periods`, which refuses an overlap.", "items": { "properties": { "daypart": { "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "type": "string" }, "days_of_week": { "items": { "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "type": "string" }, "type": "array" }, "end_time": { "type": "string" }, "start_time": { "type": "string" } }, "required": [ "daypart", "start_time", "end_time" ], "type": "object" }, "title": "Outlet meal periods", "type": "array" }, "name": { "title": "Outlet name", "type": "string" }, "usali_department": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "USALI 12 department", "type": "string" }, "usali_revenue_center_label": { "title": "USALI revenue center label", "type": "string" } }, "required": [ "code", "name", "usali_department", "usali_revenue_center_label", "kind" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.outlet:read" ] } ], "summary": "Read Outlet", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.outlet/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA USALI-conformant revenue-bearing unit. Distinct from `venue` (the physical space) because outlets are revenue-reporting categories: the rooms outlet has no venue; a banquets-and-restaurant venue can host two revenue centers (one outlet each). `usali_department` is the chart-of-accounts classification; `kind` is the operational classification — orthogonal axes, since an outlet's accounting schedule and its operational shape do not always coincide (a third-party-licensed restaurant books as `other_operated` but operates as `restaurant`).", "operationId": "get_hospitality_outlet_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.outlet" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.outlet:read" ] } ], "summary": "Read Outlet as of a watermark", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.outlet/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA USALI-conformant revenue-bearing unit. Distinct from `venue` (the physical space) because outlets are revenue-reporting categories: the rooms outlet has no venue; a banquets-and-restaurant venue can host two revenue centers (one outlet each). `usali_department` is the chart-of-accounts classification; `kind` is the operational classification — orthogonal axes, since an outlet's accounting schedule and its operational shape do not always coincide (a third-party-licensed restaurant books as `other_operated` but operates as `restaurant`).", "operationId": "list_links_hospitality_outlet", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.outlet:read" ] } ], "summary": "List links of Outlet", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.appointment_at_outlet", "hospitality.link.banquet_order_at_outlet", "hospitality.link.charge_at_outlet", "hospitality.link.check_at_outlet", "hospitality.link.device_at_outlet", "hospitality.link.menu_for_outlet", "hospitality.link.outlet_at_property", "hospitality.link.outlet_at_venue", "hospitality.link.outlet_has_parent", "hospitality.link.package_component_alternate_outlet", "hospitality.link.prep_station_at_outlet", "hospitality.link.price_at_outlet", "hospitality.link.service_area_of_outlet" ] } } ] }, "/v1/object-types/hospitality.outlet/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA USALI-conformant revenue-bearing unit. Distinct from `venue` (the physical space) because outlets are revenue-reporting categories: the rooms outlet has no venue; a banquets-and-restaurant venue can host two revenue centers (one outlet each). `usali_department` is the chart-of-accounts classification; `kind` is the operational classification — orthogonal axes, since an outlet's accounting schedule and its operational shape do not always coincide (a third-party-licensed restaurant books as `other_operated` but operates as `restaurant`).", "operationId": "traverse_hospitality_outlet", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.appointment_at_outlet", "hospitality.link.banquet_order_at_outlet", "hospitality.link.charge_at_outlet", "hospitality.link.check_at_outlet", "hospitality.link.device_at_outlet", "hospitality.link.menu_for_outlet", "hospitality.link.outlet_at_property", "hospitality.link.outlet_at_venue", "hospitality.link.outlet_has_parent", "hospitality.link.package_component_alternate_outlet", "hospitality.link.prep_station_at_outlet", "hospitality.link.price_at_outlet", "hospitality.link.service_area_of_outlet" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.outlet:read" ] } ], "summary": "Traverse from Outlet", "tags": [ "revenue" ] } }, "/v1/object-types/hospitality.outlet/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA USALI-conformant revenue-bearing unit. Distinct from `venue` (the physical space) because outlets are revenue-reporting categories: the rooms outlet has no venue; a banquets-and-restaurant venue can host two revenue centers (one outlet each). `usali_department` is the chart-of-accounts classification; `kind` is the operational classification — orthogonal axes, since an outlet's accounting schedule and its operational shape do not always coincide (a third-party-licensed restaurant books as `other_operated` but operates as `restaurant`).", "operationId": "search_hospitality_outlet", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "usali_department" }, "type": { "const": "eq" }, "value": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "usali_revenue_center_label" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "usali_revenue_center_label" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "usali_revenue_center_label" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "usali_revenue_center_label" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "rooms", "restaurant", "bar", "lounge", "room_service", "banquet", "catering", "spa", "salon", "wellness_program", "gym", "pool", "golf", "parking", "minibar", "retail", "activity", "tour", "rental", "business_center", "laundry", "telecom", "package_aggregator", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "meal_periods" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "daypart": { "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "type": "string" }, "days_of_week": { "items": { "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "type": "string" }, "type": "array" }, "end_time": { "type": "string" }, "start_time": { "type": "string" } }, "required": [ "daypart", "start_time", "end_time" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "usali_department", "usali_revenue_center_label", "kind", "description" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.outlet" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Outlet code", "type": "string" }, "description": { "title": "Description", "type": "string" }, "kind": { "enum": [ "rooms", "restaurant", "bar", "lounge", "room_service", "banquet", "catering", "spa", "salon", "wellness_program", "gym", "pool", "golf", "parking", "minibar", "retail", "activity", "tour", "rental", "business_center", "laundry", "telecom", "package_aggregator", "other" ], "title": "Operational kind", "type": "string" }, "meal_periods": { "description": "The outlet's meal periods (Simphony's serving periods, Toast's services): each a `daypart`, 24-hour `start_time` and `end_time` on the house's wall clock, and its `days_of_week`. `open_check` stamps a live check with the one in force. Written by `set_outlet_meal_periods`, which refuses an overlap.", "items": { "properties": { "daypart": { "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "type": "string" }, "days_of_week": { "items": { "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "type": "string" }, "type": "array" }, "end_time": { "type": "string" }, "start_time": { "type": "string" } }, "required": [ "daypart", "start_time", "end_time" ], "type": "object" }, "title": "Outlet meal periods", "type": "array" }, "name": { "title": "Outlet name", "type": "string" }, "usali_department": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "USALI 12 department", "type": "string" }, "usali_revenue_center_label": { "title": "USALI revenue center label", "type": "string" } }, "required": [ "code", "name", "usali_department", "usali_revenue_center_label", "kind" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.outlet:read" ] } ], "summary": "Search Outlet", "tags": [ "revenue" ] } }, "/v1/object-types/hospitality.owner_statement/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne month's owner package for one property: the USALI summary figures, the fee computation, and the budget-vs-actual-vs-prior-year snapshot, submitted by the operator inside the HMA's reporting window (contract band: 8 business days to 20 calendar days after month-end) and approved by the owner through an approval gate (the statement implements `approvable`; separation-of-duties keeps the submitter out of the deciding set). A changes_requested statement is answered by a new revision, not an edit — statements are reporting records.", "operationId": "get_hospitality_owner_statement", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.owner_statement" }, "properties": { "additionalProperties": false, "properties": { "base_fee": { "description": "Base management fee for the period", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Owner statement base fee", "type": "object" }, "decided_at": { "format": "date-time", "title": "When the owner's gate decided", "type": "string" }, "due_by": { "format": "date", "title": "Contractual delivery deadline for the period", "type": "string" }, "external_ref": { "title": "External ref", "type": "string" }, "gop": { "description": "Gross operating profit (pre-management-fee, per USALI)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Owner statement gop", "type": "object" }, "id": { "title": "Statement id", "type": "string" }, "incentive_fee": { "description": "Incentive management fee for the period (accrual or true-up)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Owner statement incentive fee", "type": "object" }, "noi": { "description": "Net operating income for the period", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Owner statement noi", "type": "object" }, "period_end": { "format": "date", "title": "Reporting-period end", "type": "string" }, "period_start": { "format": "date", "title": "Reporting-period start", "type": "string" }, "revision": { "title": "Revision number (1 = first submission for the period)", "type": "integer" }, "status": { "enum": [ "submitted", "approved", "changes_requested" ], "title": "Lifecycle status", "type": "string" }, "submitted_at": { "format": "date-time", "title": "When the operator submitted", "type": "string" }, "total_revenue": { "description": "Total operating revenue for the period", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Owner statement total revenue", "type": "object" }, "variance_snapshot": { "title": "Budget-vs-actual-vs-prior-year comparison (the Strand §9.02 columns) as reported, JSON" } }, "required": [ "id", "status", "period_start", "period_end", "due_by", "revision", "total_revenue", "submitted_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.owner_statement:read" ] } ], "summary": "Read Owner statement", "tags": [ "management" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.owner_statement/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne month's owner package for one property: the USALI summary figures, the fee computation, and the budget-vs-actual-vs-prior-year snapshot, submitted by the operator inside the HMA's reporting window (contract band: 8 business days to 20 calendar days after month-end) and approved by the owner through an approval gate (the statement implements `approvable`; separation-of-duties keeps the submitter out of the deciding set). A changes_requested statement is answered by a new revision, not an edit — statements are reporting records.", "operationId": "get_hospitality_owner_statement_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.owner_statement" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.owner_statement:read" ] } ], "summary": "Read Owner statement as of a watermark", "tags": [ "management" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.owner_statement/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne month's owner package for one property: the USALI summary figures, the fee computation, and the budget-vs-actual-vs-prior-year snapshot, submitted by the operator inside the HMA's reporting window (contract band: 8 business days to 20 calendar days after month-end) and approved by the owner through an approval gate (the statement implements `approvable`; separation-of-duties keeps the submitter out of the deciding set). A changes_requested statement is answered by a new revision, not an edit — statements are reporting records.", "operationId": "list_links_hospitality_owner_statement", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.owner_statement:read" ] } ], "summary": "List links of Owner statement", "tags": [ "management" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.approval_gate_for_owner_statement", "hospitality.link.owner_statement_for_property", "hospitality.link.owner_statement_under_agreement" ] } } ] }, "/v1/object-types/hospitality.owner_statement/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne month's owner package for one property: the USALI summary figures, the fee computation, and the budget-vs-actual-vs-prior-year snapshot, submitted by the operator inside the HMA's reporting window (contract band: 8 business days to 20 calendar days after month-end) and approved by the owner through an approval gate (the statement implements `approvable`; separation-of-duties keeps the submitter out of the deciding set). A changes_requested statement is answered by a new revision, not an edit — statements are reporting records.", "operationId": "traverse_hospitality_owner_statement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.approval_gate_for_owner_statement", "hospitality.link.owner_statement_for_property", "hospitality.link.owner_statement_under_agreement" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.owner_statement:read" ] } ], "summary": "Traverse from Owner statement", "tags": [ "management" ] } }, "/v1/object-types/hospitality.owner_statement/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne month's owner package for one property: the USALI summary figures, the fee computation, and the budget-vs-actual-vs-prior-year snapshot, submitted by the operator inside the HMA's reporting window (contract band: 8 business days to 20 calendar days after month-end) and approved by the owner through an approval gate (the statement implements `approvable`; separation-of-duties keeps the submitter out of the deciding set). A changes_requested statement is answered by a new revision, not an edit — statements are reporting records.", "operationId": "search_hospitality_owner_statement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "submitted", "approved", "changes_requested" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_start" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_start" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_start" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_end" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_end" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_end" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "due_by" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "due_by" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "due_by" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revision" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revision" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revision" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "total_revenue" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "gop" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "base_fee" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "incentive_fee" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "noi" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "variance_snapshot" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "submitted_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "submitted_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "submitted_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "status", "period_start", "period_end", "due_by", "revision", "submitted_at", "decided_at", "external_ref" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.owner_statement" }, "properties": { "additionalProperties": false, "properties": { "base_fee": { "description": "Base management fee for the period", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Owner statement base fee", "type": "object" }, "decided_at": { "format": "date-time", "title": "When the owner's gate decided", "type": "string" }, "due_by": { "format": "date", "title": "Contractual delivery deadline for the period", "type": "string" }, "external_ref": { "title": "External ref", "type": "string" }, "gop": { "description": "Gross operating profit (pre-management-fee, per USALI)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Owner statement gop", "type": "object" }, "id": { "title": "Statement id", "type": "string" }, "incentive_fee": { "description": "Incentive management fee for the period (accrual or true-up)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Owner statement incentive fee", "type": "object" }, "noi": { "description": "Net operating income for the period", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Owner statement noi", "type": "object" }, "period_end": { "format": "date", "title": "Reporting-period end", "type": "string" }, "period_start": { "format": "date", "title": "Reporting-period start", "type": "string" }, "revision": { "title": "Revision number (1 = first submission for the period)", "type": "integer" }, "status": { "enum": [ "submitted", "approved", "changes_requested" ], "title": "Lifecycle status", "type": "string" }, "submitted_at": { "format": "date-time", "title": "When the operator submitted", "type": "string" }, "total_revenue": { "description": "Total operating revenue for the period", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Owner statement total revenue", "type": "object" }, "variance_snapshot": { "title": "Budget-vs-actual-vs-prior-year comparison (the Strand §9.02 columns) as reported, JSON" } }, "required": [ "id", "status", "period_start", "period_end", "due_by", "revision", "total_revenue", "submitted_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.owner_statement:read" ] } ], "summary": "Search Owner statement", "tags": [ "management" ] } }, "/v1/object-types/hospitality.package/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA sellable bundled offering (room + dinner + spa retreat). The catalog identity / lineage object: `code` and `name` are stable across versions; wrapper pricing and allocation rule live exclusively on `package_version` rows linked via `package_has_version` / `package_has_active_version` (proposal 0024; the legacy package-level price fields were dropped in the Phase B flip). A sale freezes the specific version it was priced against via the `package_sale_uses_package_version` link plus the existing `package_sale.package_version_snapshot` JSON. All pricing writes go through `supersede_package`.", "operationId": "get_hospitality_package", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.package" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Package code", "type": "string" }, "description": { "title": "Description", "type": "string" }, "name": { "title": "Package name", "type": "string" }, "status": { "enum": [ "active", "paused", "deprecated" ], "title": "Lifecycle status", "type": "string" } }, "required": [ "code", "name", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.package:read" ] } ], "summary": "Read Package", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.package/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA sellable bundled offering (room + dinner + spa retreat). The catalog identity / lineage object: `code` and `name` are stable across versions; wrapper pricing and allocation rule live exclusively on `package_version` rows linked via `package_has_version` / `package_has_active_version` (proposal 0024; the legacy package-level price fields were dropped in the Phase B flip). A sale freezes the specific version it was priced against via the `package_sale_uses_package_version` link plus the existing `package_sale.package_version_snapshot` JSON. All pricing writes go through `supersede_package`.", "operationId": "get_hospitality_package_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.package" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.package:read" ] } ], "summary": "Read Package as of a watermark", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.package/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA sellable bundled offering (room + dinner + spa retreat). The catalog identity / lineage object: `code` and `name` are stable across versions; wrapper pricing and allocation rule live exclusively on `package_version` rows linked via `package_has_version` / `package_has_active_version` (proposal 0024; the legacy package-level price fields were dropped in the Phase B flip). A sale freezes the specific version it was priced against via the `package_sale_uses_package_version` link plus the existing `package_sale.package_version_snapshot` JSON. All pricing writes go through `supersede_package`.", "operationId": "list_links_hospitality_package", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.package:read" ] } ], "summary": "List links of Package", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.package_at_brand", "hospitality.link.package_at_property", "hospitality.link.package_has_active_version", "hospitality.link.package_has_component", "hospitality.link.package_has_version" ] } } ] }, "/v1/object-types/hospitality.package/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA sellable bundled offering (room + dinner + spa retreat). The catalog identity / lineage object: `code` and `name` are stable across versions; wrapper pricing and allocation rule live exclusively on `package_version` rows linked via `package_has_version` / `package_has_active_version` (proposal 0024; the legacy package-level price fields were dropped in the Phase B flip). A sale freezes the specific version it was priced against via the `package_sale_uses_package_version` link plus the existing `package_sale.package_version_snapshot` JSON. All pricing writes go through `supersede_package`.", "operationId": "traverse_hospitality_package", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.package_at_brand", "hospitality.link.package_at_property", "hospitality.link.package_has_active_version", "hospitality.link.package_has_component", "hospitality.link.package_has_version" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.package:read" ] } ], "summary": "Traverse from Package", "tags": [ "revenue" ] } }, "/v1/object-types/hospitality.package/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA sellable bundled offering (room + dinner + spa retreat). The catalog identity / lineage object: `code` and `name` are stable across versions; wrapper pricing and allocation rule live exclusively on `package_version` rows linked via `package_has_version` / `package_has_active_version` (proposal 0024; the legacy package-level price fields were dropped in the Phase B flip). A sale freezes the specific version it was priced against via the `package_sale_uses_package_version` link plus the existing `package_sale.package_version_snapshot` JSON. All pricing writes go through `supersede_package`.", "operationId": "search_hospitality_package", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "paused", "deprecated" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "description", "status" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.package" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Package code", "type": "string" }, "description": { "title": "Description", "type": "string" }, "name": { "title": "Package name", "type": "string" }, "status": { "enum": [ "active", "paused", "deprecated" ], "title": "Lifecycle status", "type": "string" } }, "required": [ "code", "name", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.package:read" ] } ], "summary": "Search Package", "tags": [ "revenue" ] } }, "/v1/object-types/hospitality.package_component/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne amenity inside a package: dinner-for-two, daily breakfast, an arrival massage, a $50 spa credit. Promoted to a first-class object (not link-metadata) because allocation rules, frequencies, allowances, and alternate-outlet routings don't fit on a link's edge metadata without violating Aerandil's links-carry-no-payload principle.", "operationId": "get_hospitality_package_component", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.package_component" }, "properties": { "additionalProperties": false, "properties": { "allocation_kind": { "enum": [ "per_adult", "per_room", "flat" ], "title": "How the allowance scales", "type": "string" }, "allowance_amount": { "description": "Notional contribution per occurrence", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Package component allowance amount", "type": "object" }, "daypart": { "description": "Set, the component is an F&B allowance: a room charge at one of its alternate outlets (any outlet of the house when it names none) consumes it from a check in this meal period — `all_day` is a credit for any meal. Absent, it is not food (a spa credit, parking) and the till never touches it. A `breakfast` or `brunch` allowance is eaten the morning after its night (OPERA's Post Next Day): the breakfast roster, the till and the night audit's allowance sweep all read it on the day after the night that carries it.", "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "title": "Meal period the allowance is eaten in", "type": "string" }, "frequency": { "enum": [ "every_night", "first_night", "final_night", "once" ], "title": "When during the stay the component is available", "type": "string" }, "id": { "title": "Component id", "type": "string" }, "sort_order": { "title": "Display order within package", "type": "integer" } }, "required": [ "id", "allocation_kind", "frequency" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.package_component:read" ] } ], "summary": "Read Package component", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.package_component/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne amenity inside a package: dinner-for-two, daily breakfast, an arrival massage, a $50 spa credit. Promoted to a first-class object (not link-metadata) because allocation rules, frequencies, allowances, and alternate-outlet routings don't fit on a link's edge metadata without violating Aerandil's links-carry-no-payload principle.", "operationId": "get_hospitality_package_component_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.package_component" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.package_component:read" ] } ], "summary": "Read Package component as of a watermark", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.package_component/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne amenity inside a package: dinner-for-two, daily breakfast, an arrival massage, a $50 spa credit. Promoted to a first-class object (not link-metadata) because allocation rules, frequencies, allowances, and alternate-outlet routings don't fit on a link's edge metadata without violating Aerandil's links-carry-no-payload principle.", "operationId": "list_links_hospitality_package_component", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.package_component:read" ] } ], "summary": "List links of Package component", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.charge_attributed_to_package_component", "hospitality.link.package_component_alternate_outlet", "hospitality.link.package_component_targets_service_item", "hospitality.link.package_has_component" ] } } ] }, "/v1/object-types/hospitality.package_component/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne amenity inside a package: dinner-for-two, daily breakfast, an arrival massage, a $50 spa credit. Promoted to a first-class object (not link-metadata) because allocation rules, frequencies, allowances, and alternate-outlet routings don't fit on a link's edge metadata without violating Aerandil's links-carry-no-payload principle.", "operationId": "traverse_hospitality_package_component", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.charge_attributed_to_package_component", "hospitality.link.package_component_alternate_outlet", "hospitality.link.package_component_targets_service_item", "hospitality.link.package_has_component" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.package_component:read" ] } ], "summary": "Traverse from Package component", "tags": [ "revenue" ] } }, "/v1/object-types/hospitality.package_component/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne amenity inside a package: dinner-for-two, daily breakfast, an arrival massage, a $50 spa credit. Promoted to a first-class object (not link-metadata) because allocation rules, frequencies, allowances, and alternate-outlet routings don't fit on a link's edge metadata without violating Aerandil's links-carry-no-payload principle.", "operationId": "search_hospitality_package_component", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "allocation_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "per_adult", "per_room", "flat" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "frequency" }, "type": { "const": "eq" }, "value": { "enum": [ "every_night", "first_night", "final_night", "once" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "allowance_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sort_order" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sort_order" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sort_order" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "daypart" }, "type": { "const": "eq" }, "value": { "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "allocation_kind", "frequency", "sort_order", "daypart" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.package_component" }, "properties": { "additionalProperties": false, "properties": { "allocation_kind": { "enum": [ "per_adult", "per_room", "flat" ], "title": "How the allowance scales", "type": "string" }, "allowance_amount": { "description": "Notional contribution per occurrence", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Package component allowance amount", "type": "object" }, "daypart": { "description": "Set, the component is an F&B allowance: a room charge at one of its alternate outlets (any outlet of the house when it names none) consumes it from a check in this meal period — `all_day` is a credit for any meal. Absent, it is not food (a spa credit, parking) and the till never touches it. A `breakfast` or `brunch` allowance is eaten the morning after its night (OPERA's Post Next Day): the breakfast roster, the till and the night audit's allowance sweep all read it on the day after the night that carries it.", "enum": [ "breakfast", "brunch", "lunch", "dinner", "late_night", "drinks", "dessert", "room_service", "all_day" ], "title": "Meal period the allowance is eaten in", "type": "string" }, "frequency": { "enum": [ "every_night", "first_night", "final_night", "once" ], "title": "When during the stay the component is available", "type": "string" }, "id": { "title": "Component id", "type": "string" }, "sort_order": { "title": "Display order within package", "type": "integer" } }, "required": [ "id", "allocation_kind", "frequency" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.package_component:read" ] } ], "summary": "Search Package component", "tags": [ "revenue" ] } }, "/v1/object-types/hospitality.package_component_consumption/objects/{id}": { "get": { "description": "Read an existing instance.\n\nAppend-only ledger row tying a `charge` to a `package_sale` + `package_component` on a specific business date. Opera's package_profit / package_loss reconciliation pattern, made queryable: per-night per-component the operator can see what was allowed, what was consumed, and the reconciliation outcome. Mutation of this row after insert is rejected — it is event-shaped, mirroring the event log's append-only contract.", "operationId": "get_hospitality_package_component_consumption", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.package_component_consumption" }, "properties": { "additionalProperties": false, "properties": { "allowance_amount": { "description": "What the package allotted", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Package component consumption allowance amount", "type": "object" }, "business_date": { "format": "date", "title": "Business date", "type": "string" }, "consumed_amount": { "description": "What the guest actually consumed", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Package component consumption consumed amount", "type": "object" }, "covers": { "description": "How many of the stay's entitled covers this row accounts for — the breakfast roster's tick-off, or the covers of the check a room charge consumed it from. What the roster counts as taken. Absent on rows that are not a meal.", "title": "Covers this consumption fed", "type": "integer" }, "id": { "title": "Consumption id", "type": "string" }, "reconciliation_kind": { "enum": [ "consumed", "profit", "loss", "refunded" ], "title": "Reconciliation outcome", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When the consumption was recorded", "type": "string" } }, "required": [ "id", "business_date", "consumed_amount", "reconciliation_kind", "recorded_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.package_component_consumption:read" ] } ], "summary": "Read Package component consumption", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.package_component_consumption/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nAppend-only ledger row tying a `charge` to a `package_sale` + `package_component` on a specific business date. Opera's package_profit / package_loss reconciliation pattern, made queryable: per-night per-component the operator can see what was allowed, what was consumed, and the reconciliation outcome. Mutation of this row after insert is rejected — it is event-shaped, mirroring the event log's append-only contract.", "operationId": "get_hospitality_package_component_consumption_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.package_component_consumption" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.package_component_consumption:read" ] } ], "summary": "Read Package component consumption as of a watermark", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.package_component_consumption/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nAppend-only ledger row tying a `charge` to a `package_sale` + `package_component` on a specific business date. Opera's package_profit / package_loss reconciliation pattern, made queryable: per-night per-component the operator can see what was allowed, what was consumed, and the reconciliation outcome. Mutation of this row after insert is rejected — it is event-shaped, mirroring the event log's append-only contract.", "operationId": "list_links_hospitality_package_component_consumption", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.package_component_consumption:read" ] } ], "summary": "List links of Package component consumption", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.consumption_for_charge", "hospitality.link.consumption_for_check_payment", "hospitality.link.package_sale_has_consumption" ] } } ] }, "/v1/object-types/hospitality.package_component_consumption/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nAppend-only ledger row tying a `charge` to a `package_sale` + `package_component` on a specific business date. Opera's package_profit / package_loss reconciliation pattern, made queryable: per-night per-component the operator can see what was allowed, what was consumed, and the reconciliation outcome. Mutation of this row after insert is rejected — it is event-shaped, mirroring the event log's append-only contract.", "operationId": "traverse_hospitality_package_component_consumption", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.consumption_for_charge", "hospitality.link.consumption_for_check_payment", "hospitality.link.package_sale_has_consumption" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.package_component_consumption:read" ] } ], "summary": "Traverse from Package component consumption", "tags": [ "revenue" ] } }, "/v1/object-types/hospitality.package_component_consumption/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nAppend-only ledger row tying a `charge` to a `package_sale` + `package_component` on a specific business date. Opera's package_profit / package_loss reconciliation pattern, made queryable: per-night per-component the operator can see what was allowed, what was consumed, and the reconciliation outcome. Mutation of this row after insert is rejected — it is event-shaped, mirroring the event log's append-only contract.", "operationId": "search_hospitality_package_component_consumption", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "allowance_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "consumed_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reconciliation_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "consumed", "profit", "loss", "refunded" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "covers" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "covers" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "covers" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "business_date", "reconciliation_kind", "recorded_at", "covers" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.package_component_consumption" }, "properties": { "additionalProperties": false, "properties": { "allowance_amount": { "description": "What the package allotted", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Package component consumption allowance amount", "type": "object" }, "business_date": { "format": "date", "title": "Business date", "type": "string" }, "consumed_amount": { "description": "What the guest actually consumed", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Package component consumption consumed amount", "type": "object" }, "covers": { "description": "How many of the stay's entitled covers this row accounts for — the breakfast roster's tick-off, or the covers of the check a room charge consumed it from. What the roster counts as taken. Absent on rows that are not a meal.", "title": "Covers this consumption fed", "type": "integer" }, "id": { "title": "Consumption id", "type": "string" }, "reconciliation_kind": { "enum": [ "consumed", "profit", "loss", "refunded" ], "title": "Reconciliation outcome", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When the consumption was recorded", "type": "string" } }, "required": [ "id", "business_date", "consumed_amount", "reconciliation_kind", "recorded_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.package_component_consumption:read" ] } ], "summary": "Search Package component consumption", "tags": [ "revenue" ] } }, "/v1/object-types/hospitality.package_sale/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA reservation-attached instance of a package. Freezes the package definition at sale time via `package_version_snapshot` so guests cannot be re-priced when the catalog evolves — the snapshot is the structural snapshot half of the design-spec §B.2 structured-policy + immutable-snapshot pattern. `contracted_price` is the amount the guest agreed to pay for the wrapper; `state` tracks the lifecycle from pending through consumed / refunded / cancelled.", "operationId": "get_hospitality_package_sale", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.package_sale" }, "properties": { "additionalProperties": false, "properties": { "allowance_drawn_at": { "format": "date-time", "title": "When a consumption last drew on the sale", "type": "string" }, "allowance_draws": { "description": "Counts up by one with every consumption written through the package write (a room charge's allowance, a roster tick-off, an operator's consume). The write is the sale's version check: a recorder that weighed what was left of a day's allowance writes the sale at the version it read before summing the day's rows, so a concurrent draw on the same sale turns the second into a version conflict instead of two draws on one remainder.", "title": "Consumptions recorded against the sale", "type": "integer" }, "assembled_at": { "format": "date-time", "title": "When the sale was assembled", "type": "string" }, "contracted_price": { "description": "Wrapper price at sale time", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Package sale contracted price", "type": "object" }, "id": { "title": "Sale id", "type": "string" }, "package_ref": { "format": "uuid", "title": "Convenience reference to the parent `package` lineage (proposal 0024)", "type": "string", "x-aerandil-references": "hospitality.package" }, "package_version_ref": { "format": "uuid", "title": "Frozen pin to the `package_version` row this sale was priced against (proposal 0024)", "type": "string", "x-aerandil-references": "hospitality.package_version" }, "package_version_snapshot": { "title": "Frozen package version at sale time" }, "state": { "enum": [ "pending", "confirmed", "consumed", "refunded", "cancelled" ], "title": "Sale state", "type": "string" } }, "required": [ "id", "contracted_price", "package_version_ref", "state", "assembled_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.package_sale:read" ] } ], "summary": "Read Package sale", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.package_sale/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA reservation-attached instance of a package. Freezes the package definition at sale time via `package_version_snapshot` so guests cannot be re-priced when the catalog evolves — the snapshot is the structural snapshot half of the design-spec §B.2 structured-policy + immutable-snapshot pattern. `contracted_price` is the amount the guest agreed to pay for the wrapper; `state` tracks the lifecycle from pending through consumed / refunded / cancelled.", "operationId": "get_hospitality_package_sale_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.package_sale" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.package_sale:read" ] } ], "summary": "Read Package sale as of a watermark", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.package_sale/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA reservation-attached instance of a package. Freezes the package definition at sale time via `package_version_snapshot` so guests cannot be re-priced when the catalog evolves — the snapshot is the structural snapshot half of the design-spec §B.2 structured-policy + immutable-snapshot pattern. `contracted_price` is the amount the guest agreed to pay for the wrapper; `state` tracks the lifecycle from pending through consumed / refunded / cancelled.", "operationId": "list_links_hospitality_package_sale", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.package_sale:read" ] } ], "summary": "List links of Package sale", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.charge_attributed_to_package_sale", "hospitality.link.package_sale_has_consumption", "hospitality.link.package_sale_uses_package_version", "hospitality.link.reservation_includes_package" ] } } ] }, "/v1/object-types/hospitality.package_sale/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA reservation-attached instance of a package. Freezes the package definition at sale time via `package_version_snapshot` so guests cannot be re-priced when the catalog evolves — the snapshot is the structural snapshot half of the design-spec §B.2 structured-policy + immutable-snapshot pattern. `contracted_price` is the amount the guest agreed to pay for the wrapper; `state` tracks the lifecycle from pending through consumed / refunded / cancelled.", "operationId": "traverse_hospitality_package_sale", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.charge_attributed_to_package_sale", "hospitality.link.package_sale_has_consumption", "hospitality.link.package_sale_uses_package_version", "hospitality.link.reservation_includes_package" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.package_sale:read" ] } ], "summary": "Traverse from Package sale", "tags": [ "revenue" ] } }, "/v1/object-types/hospitality.package_sale/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA reservation-attached instance of a package. Freezes the package definition at sale time via `package_version_snapshot` so guests cannot be re-priced when the catalog evolves — the snapshot is the structural snapshot half of the design-spec §B.2 structured-policy + immutable-snapshot pattern. `contracted_price` is the amount the guest agreed to pay for the wrapper; `state` tracks the lifecycle from pending through consumed / refunded / cancelled.", "operationId": "search_hospitality_package_sale", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contracted_price" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "package_version_snapshot" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "package_version_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.package_version" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "package_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.package" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "state" }, "type": { "const": "eq" }, "value": { "enum": [ "pending", "confirmed", "consumed", "refunded", "cancelled" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "assembled_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "assembled_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "assembled_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "allowance_draws" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "allowance_draws" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "allowance_draws" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "allowance_drawn_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "allowance_drawn_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "allowance_drawn_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "state", "assembled_at", "allowance_draws", "allowance_drawn_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.package_sale" }, "properties": { "additionalProperties": false, "properties": { "allowance_drawn_at": { "format": "date-time", "title": "When a consumption last drew on the sale", "type": "string" }, "allowance_draws": { "description": "Counts up by one with every consumption written through the package write (a room charge's allowance, a roster tick-off, an operator's consume). The write is the sale's version check: a recorder that weighed what was left of a day's allowance writes the sale at the version it read before summing the day's rows, so a concurrent draw on the same sale turns the second into a version conflict instead of two draws on one remainder.", "title": "Consumptions recorded against the sale", "type": "integer" }, "assembled_at": { "format": "date-time", "title": "When the sale was assembled", "type": "string" }, "contracted_price": { "description": "Wrapper price at sale time", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Package sale contracted price", "type": "object" }, "id": { "title": "Sale id", "type": "string" }, "package_ref": { "format": "uuid", "title": "Convenience reference to the parent `package` lineage (proposal 0024)", "type": "string", "x-aerandil-references": "hospitality.package" }, "package_version_ref": { "format": "uuid", "title": "Frozen pin to the `package_version` row this sale was priced against (proposal 0024)", "type": "string", "x-aerandil-references": "hospitality.package_version" }, "package_version_snapshot": { "title": "Frozen package version at sale time" }, "state": { "enum": [ "pending", "confirmed", "consumed", "refunded", "cancelled" ], "title": "Sale state", "type": "string" } }, "required": [ "id", "contracted_price", "package_version_ref", "state", "assembled_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.package_sale:read" ] } ], "summary": "Search Package sale", "tags": [ "revenue" ] } }, "/v1/object-types/hospitality.package_version/objects/{id}": { "get": { "description": "Read an existing instance.\n\nImmutable per-version content row for a `package`. Carries the wrapper price + allocation rule that were in force when the version was minted, plus a frozen content snapshot of the components that participated. The active version is the one with `version_status = active` and `effective_to IS NULL`; the operational handle is the `package_has_active_version` 1:1 link. A `package_sale` pins to a specific row via `package_sale_uses_package_version` so cross-version revenue analytics (`GROUP BY package_version_id`) are queryable.", "operationId": "get_hospitality_package_version", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.package_version" }, "properties": { "additionalProperties": false, "properties": { "allocation_rule": { "enum": [ "pro_rata", "room_residual" ], "title": "Allocation rule for this version", "type": "string" }, "content_snapshot": { "title": "Frozen component identities + per-version overrides at version-mint time (opaque to the engine)" }, "contracted_price": { "description": "Wrapper price for this version", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Package version contracted price", "type": "object" }, "effective_from": { "format": "date-time", "title": "When this version became active", "type": "string" }, "effective_to": { "format": "date-time", "title": "When this version was superseded (null while active)", "type": "string" }, "id": { "title": "Version id", "type": "string" }, "supersede_reason": { "title": "Operator note explaining the supersedence (e.g. 'Q3 seasonal repricing'). Free text; not parsed.", "type": "string" }, "supersedes_version_id": { "format": "uuid", "title": "Prior version this one replaces (null on v1; set on every subsequent supersede). Self-reference; the link surface (`package_version_supersedes`) carries the same edge for graph walks.", "type": "string", "x-aerandil-references": "hospitality.package_version" }, "version_number": { "title": "Monotonic version number (1, 2, 3, ...) per package", "type": "integer" }, "version_status": { "enum": [ "active", "superseded", "deprecated" ], "title": "Per-version status (active | superseded | deprecated)", "type": "string" } }, "required": [ "id", "version_number", "allocation_rule", "effective_from", "version_status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.package_version:read" ] } ], "summary": "Read Package version", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.package_version/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nImmutable per-version content row for a `package`. Carries the wrapper price + allocation rule that were in force when the version was minted, plus a frozen content snapshot of the components that participated. The active version is the one with `version_status = active` and `effective_to IS NULL`; the operational handle is the `package_has_active_version` 1:1 link. A `package_sale` pins to a specific row via `package_sale_uses_package_version` so cross-version revenue analytics (`GROUP BY package_version_id`) are queryable.", "operationId": "get_hospitality_package_version_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.package_version" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.package_version:read" ] } ], "summary": "Read Package version as of a watermark", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.package_version/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nImmutable per-version content row for a `package`. Carries the wrapper price + allocation rule that were in force when the version was minted, plus a frozen content snapshot of the components that participated. The active version is the one with `version_status = active` and `effective_to IS NULL`; the operational handle is the `package_has_active_version` 1:1 link. A `package_sale` pins to a specific row via `package_sale_uses_package_version` so cross-version revenue analytics (`GROUP BY package_version_id`) are queryable.", "operationId": "list_links_hospitality_package_version", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.package_version:read" ] } ], "summary": "List links of Package version", "tags": [ "revenue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.package_has_active_version", "hospitality.link.package_has_version", "hospitality.link.package_sale_uses_package_version", "hospitality.link.package_version_supersedes" ] } } ] }, "/v1/object-types/hospitality.package_version/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nImmutable per-version content row for a `package`. Carries the wrapper price + allocation rule that were in force when the version was minted, plus a frozen content snapshot of the components that participated. The active version is the one with `version_status = active` and `effective_to IS NULL`; the operational handle is the `package_has_active_version` 1:1 link. A `package_sale` pins to a specific row via `package_sale_uses_package_version` so cross-version revenue analytics (`GROUP BY package_version_id`) are queryable.", "operationId": "traverse_hospitality_package_version", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.package_has_active_version", "hospitality.link.package_has_version", "hospitality.link.package_sale_uses_package_version", "hospitality.link.package_version_supersedes" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.package_version:read" ] } ], "summary": "Traverse from Package version", "tags": [ "revenue" ] } }, "/v1/object-types/hospitality.package_version/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nImmutable per-version content row for a `package`. Carries the wrapper price + allocation rule that were in force when the version was minted, plus a frozen content snapshot of the components that participated. The active version is the one with `version_status = active` and `effective_to IS NULL`; the operational handle is the `package_has_active_version` 1:1 link. A `package_sale` pins to a specific row via `package_sale_uses_package_version` so cross-version revenue analytics (`GROUP BY package_version_id`) are queryable.", "operationId": "search_hospitality_package_version", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "version_number" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "version_number" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "version_number" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contracted_price" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "allocation_rule" }, "type": { "const": "eq" }, "value": { "enum": [ "pro_rata", "room_residual" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "content_snapshot" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "version_status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "superseded", "deprecated" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "supersede_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "supersede_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "supersedes_version_id" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.package_version" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "version_number", "allocation_rule", "effective_from", "effective_to", "version_status", "supersede_reason" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.package_version" }, "properties": { "additionalProperties": false, "properties": { "allocation_rule": { "enum": [ "pro_rata", "room_residual" ], "title": "Allocation rule for this version", "type": "string" }, "content_snapshot": { "title": "Frozen component identities + per-version overrides at version-mint time (opaque to the engine)" }, "contracted_price": { "description": "Wrapper price for this version", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Package version contracted price", "type": "object" }, "effective_from": { "format": "date-time", "title": "When this version became active", "type": "string" }, "effective_to": { "format": "date-time", "title": "When this version was superseded (null while active)", "type": "string" }, "id": { "title": "Version id", "type": "string" }, "supersede_reason": { "title": "Operator note explaining the supersedence (e.g. 'Q3 seasonal repricing'). Free text; not parsed.", "type": "string" }, "supersedes_version_id": { "format": "uuid", "title": "Prior version this one replaces (null on v1; set on every subsequent supersede). Self-reference; the link surface (`package_version_supersedes`) carries the same edge for graph walks.", "type": "string", "x-aerandil-references": "hospitality.package_version" }, "version_number": { "title": "Monotonic version number (1, 2, 3, ...) per package", "type": "integer" }, "version_status": { "enum": [ "active", "superseded", "deprecated" ], "title": "Per-version status (active | superseded | deprecated)", "type": "string" } }, "required": [ "id", "version_number", "allocation_rule", "effective_from", "version_status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.package_version:read" ] } ], "summary": "Search Package version", "tags": [ "revenue" ] } }, "/v1/object-types/hospitality.participant_dispatch_attempt/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne row per envelope the coordinator sent to a participant runner. Records the envelope id, the parent run, the participation (federated) or workflow step (workflow), attempt counters, last HTTP outcome, last failure reason, dead-letter reference, and lifecycle status. The dispatcher worker that fills this table lands with the runner / dispatcher implementation proposal; this proposal lands only the durable state shape per 0022 §17.1.", "operationId": "get_hospitality_participant_dispatch_attempt", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.participant_dispatch_attempt" }, "properties": { "additionalProperties": false, "properties": { "aerandil_correlation_id": { "title": "Aerandil-domain correlation id copied from the parent workflow / federated run at row-creation time. Surfaced into `delivery_failed.coordinator.aerandil_correlation_id` (proposal 0022 §7.4) so the audit envelope can join back to the parent run without re-reading it. Distinct from W3C `traceparent` / `tracestate` (HTTP transport-level tracing) — this is the Aerandil domain id, not an OpenTelemetry span id.", "type": "string" }, "attempt_count": { "title": "Number of HTTP / SSE attempts made so far. Starts at 1 on first dispatch; the dispatcher increments per retry. 0022 §11.2 caps this at 7 by default.", "type": "integer" }, "claim_expires_at": { "format": "date-time", "title": "Visibility lease for a dispatcher worker that has claimed this pending row. Once elapsed, another worker may claim it after a crash or deploy.", "type": "string" }, "dead_letter_reference": { "title": "Opaque pointer to the dead-letter record once retries are exhausted. The dead-letter store choice is implementation-specific per 0022 §4.2 / §16.2 open question 7 — this is just the reference.", "type": "string" }, "dispatch_kind": { "title": "CloudEvents `type` discriminator — `federated_contribution_request`, `workflow_step_invocation`, `federated_output_quarantine`, etc. per 0022 §5.5 / §7.", "type": "string" }, "dispatch_payload": { "title": "Kind-specific §7 data fragment the dispatcher folds into the outbound envelope's data block at send time — e.g. the §7.5 `quarantine` object for `federated_output_quarantine` rows (output id, incident id, quarantine reason, operator actions). Null for kinds whose data block is assembled entirely from the denormalised columns." }, "envelope_expires_at": { "format": "date-time", "title": "Hard deadline copied from `data.idempotency.envelope_expires_at`. The dispatcher stops retrying and marks the attempt `expired` after this time.", "type": "string" }, "envelope_id": { "title": "CloudEvents `id` carried by this dispatch (UUID v7). Reused on retry; same envelope_id across attempts of one logical dispatch.", "type": "string" }, "first_attempt_at": { "format": "date-time", "title": "Wall-clock time of the first dispatch attempt.", "type": "string" }, "id": { "title": "Dispatch attempt id", "type": "string" }, "last_attempt_at": { "format": "date-time", "title": "Wall-clock time of the most recent dispatch attempt.", "type": "string" }, "last_failure_reason": { "title": "Free-text failure reason from the most recent failed attempt — transport error, signature verification failure, expired envelope, etc. Cleared on a successful delivery.", "type": "string" }, "last_http_status": { "title": "HTTP status code from the most recent attempt. Null until the first attempt completes with a parseable response; set on every attempt afterwards.", "type": "integer" }, "next_attempt_at": { "format": "date-time", "title": "Dispatcher retry timer. Null / absent means immediately claimable; a future value parks the row until that time.", "type": "string" }, "status": { "enum": [ "pending", "in_flight", "acknowledged", "delivered", "failed", "expired" ], "title": "Lifecycle status — pending → acknowledged → delivered (success), or → failed (retries exhausted) / expired (past `envelope_expires_at`).", "type": "string" }, "target_agent_installation_id": { "title": "`agent_installation.id` (business id) for `workflow_step_invocation` dispatches — the endpoint resolver reads the installation's `dispatch_endpoint_url` and the receiver verifies participant signatures against its `runner_public_keys`. Null for participation-anchored (federated) dispatch kinds.", "type": "string" }, "target_participation_id": { "title": "`federated_participation.id` for federated dispatches; null for workflow agent-installation dispatches.", "type": "string" }, "target_run_id": { "title": "Parent `federated_run.id` or `workflow_run.id`. The link surface carries the typed traversal; this column is the denormalised id for fast lookup. Exactly one of the two parent-run link types is populated per row.", "type": "string" }, "target_step_run_id": { "title": "`workflow_step_run` object uuid for `workflow_step_invocation` dispatches — the receiver's completion binding advances this step via `record_workflow_step_attempt` / `record_workflow_step_result` when the participant submits its result. Null for federated kinds.", "type": "string" }, "target_subject": { "title": "CloudEvents `subject` attribute the envelope carried. Composite string per 0022 §5.4 — `//` for federated, `//` for workflow; `/` for §7.5 quarantine notices.", "type": "string" } }, "required": [ "id", "envelope_id", "dispatch_kind", "target_subject", "attempt_count", "first_attempt_at", "last_attempt_at", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.participant_dispatch_attempt:read" ] } ], "summary": "Read Participant dispatch attempt", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.participant_dispatch_attempt/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne row per envelope the coordinator sent to a participant runner. Records the envelope id, the parent run, the participation (federated) or workflow step (workflow), attempt counters, last HTTP outcome, last failure reason, dead-letter reference, and lifecycle status. The dispatcher worker that fills this table lands with the runner / dispatcher implementation proposal; this proposal lands only the durable state shape per 0022 §17.1.", "operationId": "get_hospitality_participant_dispatch_attempt_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.participant_dispatch_attempt" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.participant_dispatch_attempt:read" ] } ], "summary": "Read Participant dispatch attempt as of a watermark", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.participant_dispatch_attempt/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne row per envelope the coordinator sent to a participant runner. Records the envelope id, the parent run, the participation (federated) or workflow step (workflow), attempt counters, last HTTP outcome, last failure reason, dead-letter reference, and lifecycle status. The dispatcher worker that fills this table lands with the runner / dispatcher implementation proposal; this proposal lands only the durable state shape per 0022 §17.1.", "operationId": "list_links_hospitality_participant_dispatch_attempt", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.participant_dispatch_attempt:read" ] } ], "summary": "List links of Participant dispatch attempt", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.participant_dispatch_for_run", "hospitality.link.participant_dispatch_for_workflow_run" ] } } ] }, "/v1/object-types/hospitality.participant_dispatch_attempt/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne row per envelope the coordinator sent to a participant runner. Records the envelope id, the parent run, the participation (federated) or workflow step (workflow), attempt counters, last HTTP outcome, last failure reason, dead-letter reference, and lifecycle status. The dispatcher worker that fills this table lands with the runner / dispatcher implementation proposal; this proposal lands only the durable state shape per 0022 §17.1.", "operationId": "traverse_hospitality_participant_dispatch_attempt", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.participant_dispatch_for_run", "hospitality.link.participant_dispatch_for_workflow_run" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.participant_dispatch_attempt:read" ] } ], "summary": "Traverse from Participant dispatch attempt", "tags": [ "federated_intelligence" ] } }, "/v1/object-types/hospitality.participant_dispatch_attempt/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne row per envelope the coordinator sent to a participant runner. Records the envelope id, the parent run, the participation (federated) or workflow step (workflow), attempt counters, last HTTP outcome, last failure reason, dead-letter reference, and lifecycle status. The dispatcher worker that fills this table lands with the runner / dispatcher implementation proposal; this proposal lands only the durable state shape per 0022 §17.1.", "operationId": "search_hospitality_participant_dispatch_attempt", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "envelope_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "envelope_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "envelope_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "envelope_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispatch_kind" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispatch_kind" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispatch_kind" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispatch_kind" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_run_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_run_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_run_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_run_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_participation_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_participation_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_participation_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_participation_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_agent_installation_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_agent_installation_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_agent_installation_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_agent_installation_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_step_run_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_step_run_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_step_run_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_step_run_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "aerandil_correlation_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "aerandil_correlation_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "aerandil_correlation_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "aerandil_correlation_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_subject" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_subject" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_subject" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_subject" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispatch_payload" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "attempt_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "attempt_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "attempt_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "first_attempt_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "first_attempt_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "first_attempt_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_attempt_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_attempt_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_attempt_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_http_status" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_http_status" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_http_status" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_failure_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_failure_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_attempt_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_attempt_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_attempt_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "envelope_expires_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "envelope_expires_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "envelope_expires_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "claim_expires_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "claim_expires_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "claim_expires_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dead_letter_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dead_letter_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dead_letter_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dead_letter_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "pending", "in_flight", "acknowledged", "delivered", "failed", "expired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "envelope_id", "dispatch_kind", "target_run_id", "target_participation_id", "target_agent_installation_id", "target_step_run_id", "aerandil_correlation_id", "target_subject", "attempt_count", "first_attempt_at", "last_attempt_at", "last_http_status", "last_failure_reason", "next_attempt_at", "envelope_expires_at", "claim_expires_at", "dead_letter_reference", "status" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.participant_dispatch_attempt" }, "properties": { "additionalProperties": false, "properties": { "aerandil_correlation_id": { "title": "Aerandil-domain correlation id copied from the parent workflow / federated run at row-creation time. Surfaced into `delivery_failed.coordinator.aerandil_correlation_id` (proposal 0022 §7.4) so the audit envelope can join back to the parent run without re-reading it. Distinct from W3C `traceparent` / `tracestate` (HTTP transport-level tracing) — this is the Aerandil domain id, not an OpenTelemetry span id.", "type": "string" }, "attempt_count": { "title": "Number of HTTP / SSE attempts made so far. Starts at 1 on first dispatch; the dispatcher increments per retry. 0022 §11.2 caps this at 7 by default.", "type": "integer" }, "claim_expires_at": { "format": "date-time", "title": "Visibility lease for a dispatcher worker that has claimed this pending row. Once elapsed, another worker may claim it after a crash or deploy.", "type": "string" }, "dead_letter_reference": { "title": "Opaque pointer to the dead-letter record once retries are exhausted. The dead-letter store choice is implementation-specific per 0022 §4.2 / §16.2 open question 7 — this is just the reference.", "type": "string" }, "dispatch_kind": { "title": "CloudEvents `type` discriminator — `federated_contribution_request`, `workflow_step_invocation`, `federated_output_quarantine`, etc. per 0022 §5.5 / §7.", "type": "string" }, "dispatch_payload": { "title": "Kind-specific §7 data fragment the dispatcher folds into the outbound envelope's data block at send time — e.g. the §7.5 `quarantine` object for `federated_output_quarantine` rows (output id, incident id, quarantine reason, operator actions). Null for kinds whose data block is assembled entirely from the denormalised columns." }, "envelope_expires_at": { "format": "date-time", "title": "Hard deadline copied from `data.idempotency.envelope_expires_at`. The dispatcher stops retrying and marks the attempt `expired` after this time.", "type": "string" }, "envelope_id": { "title": "CloudEvents `id` carried by this dispatch (UUID v7). Reused on retry; same envelope_id across attempts of one logical dispatch.", "type": "string" }, "first_attempt_at": { "format": "date-time", "title": "Wall-clock time of the first dispatch attempt.", "type": "string" }, "id": { "title": "Dispatch attempt id", "type": "string" }, "last_attempt_at": { "format": "date-time", "title": "Wall-clock time of the most recent dispatch attempt.", "type": "string" }, "last_failure_reason": { "title": "Free-text failure reason from the most recent failed attempt — transport error, signature verification failure, expired envelope, etc. Cleared on a successful delivery.", "type": "string" }, "last_http_status": { "title": "HTTP status code from the most recent attempt. Null until the first attempt completes with a parseable response; set on every attempt afterwards.", "type": "integer" }, "next_attempt_at": { "format": "date-time", "title": "Dispatcher retry timer. Null / absent means immediately claimable; a future value parks the row until that time.", "type": "string" }, "status": { "enum": [ "pending", "in_flight", "acknowledged", "delivered", "failed", "expired" ], "title": "Lifecycle status — pending → acknowledged → delivered (success), or → failed (retries exhausted) / expired (past `envelope_expires_at`).", "type": "string" }, "target_agent_installation_id": { "title": "`agent_installation.id` (business id) for `workflow_step_invocation` dispatches — the endpoint resolver reads the installation's `dispatch_endpoint_url` and the receiver verifies participant signatures against its `runner_public_keys`. Null for participation-anchored (federated) dispatch kinds.", "type": "string" }, "target_participation_id": { "title": "`federated_participation.id` for federated dispatches; null for workflow agent-installation dispatches.", "type": "string" }, "target_run_id": { "title": "Parent `federated_run.id` or `workflow_run.id`. The link surface carries the typed traversal; this column is the denormalised id for fast lookup. Exactly one of the two parent-run link types is populated per row.", "type": "string" }, "target_step_run_id": { "title": "`workflow_step_run` object uuid for `workflow_step_invocation` dispatches — the receiver's completion binding advances this step via `record_workflow_step_attempt` / `record_workflow_step_result` when the participant submits its result. Null for federated kinds.", "type": "string" }, "target_subject": { "title": "CloudEvents `subject` attribute the envelope carried. Composite string per 0022 §5.4 — `//` for federated, `//` for workflow; `/` for §7.5 quarantine notices.", "type": "string" } }, "required": [ "id", "envelope_id", "dispatch_kind", "target_subject", "attempt_count", "first_attempt_at", "last_attempt_at", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.participant_dispatch_attempt:read" ] } ], "summary": "Search Participant dispatch attempt", "tags": [ "federated_intelligence" ] } }, "/v1/object-types/hospitality.payment/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA payment applied to a folio. Settles charges. Refunds are recorded as a **separate negative-amount Payment row** linked to the original settled payment via `payment_refunds_payment` and carrying `payment_kind = refund` per proposal 0019. The original settled Payment row stays immutable — `status = settled` is the evidence that money was captured, and partial-refund / multiple-refund state is derived from the linked refund legs rather than by rewriting the source row.", "operationId": "get_hospitality_payment", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment" }, "properties": { "additionalProperties": false, "properties": { "acquirer_reference_number": { "title": "23-digit ARN (Acquirer Reference Number) assigned post-clearing. The cross-network join key for chargeback investigation; load-bearing at dispute time. Often unavailable at capture time (lands hours later via PSP reconciliation report); populated as a follow-up enrichment when present. Mastercard Banknet Reference and Visa Transaction Identifier (TID, DE 62.2) network references are deferred to a structured sub-object per proposal 0018 §10.2.", "type": "string" }, "amount": { "description": "Amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment amount", "type": "object" }, "auth_correlation_id": { "title": "Host's PSP authorisation reference (Stripe payment_intent_id, Adyen pspReference, Worldpay transactionReference). Per-payment join key for reconciling PSP-side records with the Aerandil audit trail.", "type": "string" }, "authentication_outcome": { "enum": [ "frictionless", "challenge_passed", "challenge_failed", "attempted", "pending_decoupled", "not_applicable" ], "title": "EMV 3DS 2.2 authentication result on this authorisation. `pending_decoupled` covers the EMVCo 2.2 decoupled async flow (up to 7 days for the result to land).", "type": "string" }, "authorisation_expires_at": { "format": "date-time", "title": "Scheme's authorisation-validity window (Visa 30 days for MCC 3501-7011 lodging, Mastercard 7 days final auth / 30 days pre-auth, Amex 7 days). Set by the host at authorisation time per their PSP integration; `authorisation_expiry_beyond_scheme_window` soft-warns at > 30 days.", "type": "string" }, "captured_at": { "format": "date-time", "title": "Wall-clock timestamp when the capture transitioned `status = pending → settled` via `capture_authorised_charge`. Distinct from `received_at` (set at authorisation time). Null for rows that reached `settled` via the direct-settle `apply_payment` path or historical rows pre-dating proposal 0018.", "type": "string" }, "card_present": { "title": "Whether the payment was priced as card-present (a terminal) rather than online", "type": "boolean" }, "decision_provider": { "title": "Fraud-decision vendor (denormalised from the gating assessment's vendor_id; cohort key for chargeback-rate analytics per fraud-vendor)", "type": "string" }, "decision_provider_case_id": { "title": "Vendor's case / decision identifier (Stripe Radar evaluation id, Adyen case ref, Riskified decision id, Forter forterDecisionId, Signifyd case id, Sift event id, Kount tran id). The chargeback-dispute exhibit pointer.", "type": "string" }, "external_ref": { "title": "Source-system key for connector-landed payments", "type": "string" }, "fee_class": { "enum": [ "domestic_standard", "domestic_premium", "regional", "international" ], "title": "The card's class the platform's fee was priced by — `domestic_standard`, `domestic_premium`, `regional` or `international`, read from the card's issuing country against the account's", "type": "string" }, "fee_true_up": { "description": "Set by `record_page_fee` on a payment a hosted page took: `refunded` (the difference to the card's own class was refunded), `not_due` (nothing to give back), `refused` (the processor refused the refund; the hotel paid the ceiling, `fee_true_up_detail` says why, and the operator's variance shows it). Absent on every other payment.", "enum": [ "refunded", "not_due", "refused" ], "title": "How the page's fee came out", "type": "string" }, "fee_true_up_detail": { "title": "The processor's words for a refused fee refund", "type": "string" }, "fee_true_up_reference": { "description": "The processor's id for the application-fee refund the page's true-up made (Stripe `fr_…`).", "title": "The processor's refund of the platform's fee", "type": "string" }, "fraud_warning_actionable": { "title": "Whether the processor still calls the warning actionable — not yet disputed and not refunded in full", "type": "boolean" }, "fraud_warning_at": { "description": "Set when an issuer flags this payment as suspected fraud (an early fraud warning: Visa's TC40, Mastercard's SAFE report). About 40% of Visa and Mastercard warnings become fraud disputes when the charge is not refunded, and Visa's VAMP counts the warning itself whatever happens next. Absent on a payment no issuer has flagged.", "format": "date-time", "title": "When the issuer's early fraud warning was raised", "type": "string" }, "fraud_warning_detail": { "title": "Why the card rail responded as it did, in words", "type": "string" }, "fraud_warning_observed_at": { "format": "date-time", "title": "The processor's time of the latest report about the warning on file — the watermark an out-of-order report is checked against", "type": "string" }, "fraud_warning_reference": { "description": "Stripe's `issfr_…` for the early fraud warning an issuer raised on this payment's charge — the join key for every later report about the same warning.", "title": "The processor's id for the issuer's early fraud warning", "type": "string" }, "fraud_warning_response": { "description": "Decided once, from the stay, when the warning first arrives: `hold_voided` (an uncaptured hold released before capture — the cardholder cannot dispute it), `refunded` (a captured line after the stay at or under the house's ceiling, refunded in full), `desk_review` (a deposit before arrival, a stay in house, a line above the ceiling, or a release or refund the ledger refused — a person decides), `not_actionable` (already disputed or refunded, or nothing left to act on).", "enum": [ "hold_voided", "refunded", "desk_review", "not_actionable" ], "title": "What the card rail did about the warning", "type": "string" }, "fraud_warning_stay_phase": { "enum": [ "before_arrival", "in_house", "ended", "no_booking" ], "title": "Where the booking stood when the warning arrived", "type": "string" }, "fraud_warning_type": { "enum": [ "card_never_received", "fraudulent_card_application", "made_with_counterfeit_card", "made_with_lost_card", "made_with_stolen_card", "misc", "unauthorized_use_of_card" ], "title": "The kind of fraud the issuer labelled", "type": "string" }, "hold_decided_at": { "format": "date-time", "title": "When check-out decided this hold", "type": "string" }, "hold_decision": { "description": "Set on a pending card hold when its stay checks out: `release` (the card rail voids it), `capture` (the bill still owed money — the rail takes that from the hold, which lets the rest go), or `keep` (the house's post-stay window is on; the hold stays for charges found after departure until `hold_kept_until`). Absent on a hold no departure has decided.", "enum": [ "release", "capture", "keep" ], "title": "What check-out decided for this hold", "type": "string" }, "hold_kept_until": { "format": "date-time", "title": "Until when a kept hold is kept for post-stay charges", "type": "string" }, "hold_outcome": { "enum": [ "released", "captured", "lapsed", "unresolved" ], "title": "What became of a decided hold at the processor: released, captured, lapsed, or unresolved (still pending; the desk settles it)", "type": "string" }, "hold_outcome_detail": { "title": "The processor's words when a hold's outcome is unresolved", "type": "string" }, "hold_purpose": { "description": "Set on a card hold when it is placed: `booking` (the guarantee before arrival — the pay page's hold, or a desk hold on the booking's own account), `check_in` (the desk's hold on the stay's folio), `top_up`, `re_placement` (the card rail renewing a booking hold before the issuer lapses it), `incidentals`, `no_show`, `post_stay`, or `other`. A hold carried from the booking onto the stay at check-in keeps `booking`. Absent on a payment taken in one step.", "enum": [ "booking", "check_in", "top_up", "re_placement", "incidentals", "no_show", "post_stay", "other" ], "title": "Why this hold was placed", "type": "string" }, "id": { "title": "Payment id", "type": "string" }, "liability_shift_basis": { "enum": [ "three_ds2_authenticated", "provider_guarantee", "none" ], "title": "Why a chargeback would shift away from the merchant. Per-decision, not per-vendor.", "type": "string" }, "method": { "enum": [ "cash", "credit_card", "debit_card", "bank_transfer", "voucher", "loyalty_points", "direct_billing", "mobile_wallet", "ota_collected", "other" ], "title": "Method", "type": "string" }, "net_to_hotel": { "description": "What the transfer to the hotel carried less the application fee the platform took back, net of any transfer reversal or fee refund a refund made — the platform's balance transactions for the payment, folded by `record_processor_fee`. Equals the hotel's own payout line for the charge (amount less fee). Chargeback movements are the case's (`platform_dispute_cost`), not counted here.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment net to hotel", "type": "object" }, "payment_kind": { "enum": [ "payment", "deposit", "refund" ], "title": "Ledger-leg discriminator. `payment` is the original payment authorisation / settlement; `deposit` is a pre-arrival payment taken by `record_deposit_payment` (a refund settling against it is recorded on the booking as deposit returned); `refund` is a negative-amount leg created by `refund_payment` and linked to the original via `payment_refunds_payment`. Unset legacy rows are interpreted as `payment` by handler-level coherence rules. The companion `void_authorisation` action (proposal 0018) is gated to `payment_kind = payment` rows by the `void_requires_payment_kind_payment` validator so refund legs resolve through `resolve_payment_refund` instead.", "type": "string" }, "payment_method_token": { "title": "PSP-issued opaque token referencing the cardholder data in the operator's PSP / vault. Must NOT be a Luhn-passing 13-19-digit sequence — `payment_token_no_pan_shape` hard validator enforces PCI-DSS 4.0 (PAN never enters Aerandil).", "type": "string" }, "platform_fee": { "description": "The platform's fee on this card payment as the account's fee schedule priced it for the card's class (`fee_class`, `card_present`) — the processor's `application_fee_amount`, set when the money was taken, on what was taken. Absent on a payment that settled to the platform's own account.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment platform fee", "type": "object" }, "platform_fee_refunded": { "description": "What of the platform's fee the card rail refunded to the hotel when the hosted page this payment came from completed: the link fixed its fee at the account's dearest card class (`payment_request.page_fee_ceiling`), and the difference to the class of the card the guest paid with went back as an application-fee refund. `platform_fee` is what the platform kept. Zero when nothing was due or the refund was refused (`fee_true_up`). In the payment's currency.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment platform fee refunded", "type": "object" }, "processor_fee": { "description": "Stripe's actual processing fee on the payment's charge, read off the platform's balance transaction for it (its `fee`; a partial capture's reversal line counted in) by `record_processor_fee`. On a destination charge the fee is the platform's, recouped through the application fee — `processor_fee` beside `processor_fee_estimate` is the variance the pricing decision reports per account per month; the hotel is never trued up. In the platform's balance currency.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment processor fee", "type": "object" }, "processor_fee_estimate": { "description": "The processor's published rate for the card's class on what was taken (its conversion fee added when the charge's currency is not the schedule's) — the estimate `processor_fee` is read back against. In the charge's currency.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment processor fee estimate", "type": "object" }, "psp_capture_reference": { "title": "PSP-issued reference to the capture leg, distinct from the auth's `auth_correlation_id`. Stripe `latest_charge.id`; Adyen `/captures` response `pspReference` (a new pspRef distinct from the auth pspRef); Checkout.com `action_id`; Cybersource capture `id`. Per-payment join key for reconciliation with PSP-side records.", "type": "string" }, "psp_refund_reference": { "title": "PSP-issued refund reference: Stripe `refund.id`, Adyen refund response `pspReference` (a new pspRef distinct from the capture pspRef), Checkout.com refund `action_id`, Worldpay refund event link / reference, Braintree refund transaction id, Cybersource credit id, Mews `RefundId`. Per-leg join key for reconciliation with PSP-side refund records; may be unavailable at request time and populated later by `resolve_payment_refund`.", "type": "string" }, "psp_void_reference": { "title": "PSP-issued reference to the void / cancel / reversal leg. Stripe PaymentIntent state-transition event id; Adyen `/cancels` or `/reversals` response `pspReference`; Checkout.com `action_id`.", "type": "string" }, "received_at": { "format": "date-time", "title": "Received at", "type": "string" }, "reference": { "title": "Reference", "type": "string" }, "refund_correlation_id": { "title": "Host-side idempotency / reconciliation key for the refund request. Required by `refund_payment` because two legitimate same-amount partial refunds with the same reason can occur against one payment — amount + reason alone cannot key the idempotency cache. If the PSP refund reference is already known synchronously, the host may reuse it here; otherwise the host generates a stable correlation id and stores the later `psp_refund_reference` on resolution.", "type": "string" }, "refund_failure_reason": { "title": "PSP / network reason for a failed or voided refund leg (e.g. `declined`, `insufficient_funds`, closed account, processor settlement decline, operator cancellation). Required at the handler level when `resolve_payment_refund(refund_status = failed)`; optional otherwise. Free-form because PSPs do not converge on a closed taxonomy of refund-failure codes — Stripe, Adyen, Braintree, and Cybersource each expose their own error vocabulary that the host typically pastes through verbatim.", "type": "string" }, "refund_note": { "title": "Free-form human-readable colour on a refund leg, complementing the closed `refund_reason` enum. Required when `refund_reason = other`; optional otherwise. Capped at 1024 characters at the handler level.", "type": "string" }, "refund_reason": { "enum": [ "duplicate", "fraudulent", "requested_by_customer", "reservation_cancelled", "deposit_return", "service_recovery", "overcharge_correction", "no_show_policy_exception", "package_component_refund", "membership_cancellation", "chargeback_prevention", "other", "chargeback_lost" ], "title": "Closed reason taxonomy on a refund leg. Stripe / Adyen canonical three (`duplicate`, `fraudulent`, `requested_by_customer`) plus nine Aerandil-domain hospitality reasons (`reservation_cancelled`, `deposit_return`, `service_recovery`, `overcharge_correction`, `no_show_policy_exception`, `package_component_refund`, `membership_cancellation`, `chargeback_prevention`, `other`), and `chargeback_lost` — the leg `record_payment_dispute` writes when a chargeback is lost, which `refund_payment` never accepts. Required at the handler level for `refund_payment`; optional on the property because third-party importers may write refund rows without one. `other` requires `refund_note` per the `refund_other_requires_note` validator.", "type": "string" }, "refund_requested_at": { "format": "date-time", "title": "Timestamp when the host recorded the refund request / PSP accepted the refund request. For refund rows, the required `received_at` mirrors this timestamp so legacy ledger queries that group by `received_at` continue to work without per-leg date logic.", "type": "string" }, "refund_resolved_at": { "format": "date-time", "title": "Timestamp when the refund leg reached a terminal outcome (`status = refunded`, `failed`, or `voided`). Null while the leg is `pending`. Populated by `resolve_payment_refund`, or by `refund_payment` when `refund_initial_status = refunded` for a synchronously-confirmed refund.", "type": "string" }, "refund_trace_reference": { "title": "Downstream trace reference the cardholder can take to their bank when the refund is not visible on the card. Stripe documents ARN / STAN / RRN for this purpose; often lands days after the refund request via PSP reconciliation. Typed by `refund_trace_reference_type` so the operator knows which network reference to quote — Visa ARN, network STAN, network RRN, or a PSP-internal trace handle.", "type": "string" }, "refund_trace_reference_type": { "enum": [ "arn", "stan", "rrn", "psp_generated", "unavailable" ], "title": "Type tag on `refund_trace_reference`. `arn` (23-digit Acquirer Reference Number); `stan` (System Trace Audit Number); `rrn` (Retrieval Reference Number); `psp_generated` (PSP-internal handle when the network reference is not yet exposed); `unavailable` (same-day reversals and pre-clearing refunds may have no traceable network reference at all). Kept separate from 0018's `acquirer_reference_number` because refund reversals can lack an ARN while still having STAN / RRN evidence; `refund_trace_reference_type_coherence` enforces the reference / type pairing.", "type": "string" }, "review_state": { "enum": [ "not_required", "held", "approved", "declined", "expired" ], "title": "Post-network review-hold state. `not_required` for direct-capture flows; `held` for manual_capture_after_review with a held_for_review outcome; `approved` / `declined` / `expired` are terminal states transitioned atomically by the `capture_authorised_charge` and `void_authorisation` companion actions (proposals 0017 §6.2 and 0018 §6).", "type": "string" }, "sca_exemption_claimed": { "enum": [ "none", "low_value", "tra", "mit", "trusted_beneficiary", "secure_corporate" ], "title": "PSD2 SCA exemption claimed by the host at authorisation time. The PSP is the source of truth on whether the exemption was actually granted; Aerandil records the claim plus the amount-ceiling sanity validators.", "type": "string" }, "status": { "enum": [ "pending", "settled", "refunded", "voided", "failed" ], "title": "Status", "type": "string" }, "void_note": { "title": "Free-form human-readable colour on a voided payment, complementing the closed `void_reason` enum. Mirrors Adyen's open `reference` field pattern. Capped at 1024 characters at the handler level.", "type": "string" }, "void_reason": { "enum": [ "duplicate", "fraudulent", "requested_by_customer", "abandoned", "review_declined", "authorisation_expired", "reservation_cancelled", "guest_disputed_pre_arrival", "released_at_departure" ], "title": "Closed reason taxonomy on a voided payment. Stripe-aligned canonical four (`duplicate`, `fraudulent`, `requested_by_customer`, `abandoned`) plus Aerandil-domain hospitality four (`review_declined`, `authorisation_expired`, `reservation_cancelled`, `guest_disputed_pre_arrival`). Required at the handler level for `void_authorisation`; optional on the property because third-party importers may write voided rows without one. PSP-side capture-failure events (Adyen `CAPTURE_FAILED`, Checkout.com capture-declined) are deliberately excluded — see proposal 0018 §1 and §10.1.", "type": "string" }, "voided_at": { "format": "date-time", "title": "Wall-clock timestamp when the void transitioned `status = pending → voided` via `void_authorisation`. Populated by the void handler; null otherwise.", "type": "string" } }, "required": [ "id", "amount", "method", "received_at", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payment:read" ] } ], "summary": "Read Payment", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.payment/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA payment applied to a folio. Settles charges. Refunds are recorded as a **separate negative-amount Payment row** linked to the original settled payment via `payment_refunds_payment` and carrying `payment_kind = refund` per proposal 0019. The original settled Payment row stays immutable — `status = settled` is the evidence that money was captured, and partial-refund / multiple-refund state is derived from the linked refund legs rather than by rewriting the source row.", "operationId": "get_hospitality_payment_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.payment" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payment:read" ] } ], "summary": "Read Payment as of a watermark", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.payment/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA payment applied to a folio. Settles charges. Refunds are recorded as a **separate negative-amount Payment row** linked to the original settled payment via `payment_refunds_payment` and carrying `payment_kind = refund` per proposal 0019. The original settled Payment row stays immutable — `status = settled` is the evidence that money was captured, and partial-refund / multiple-refund state is derived from the linked refund legs rather than by rewriting the source row.", "operationId": "list_links_hospitality_payment", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payment:read" ] } ], "summary": "List links of Payment", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.cashier_transaction_mirrors_payment", "hospitality.link.dispute_for_payment", "hospitality.link.folio_has_payment", "hospitality.link.fraud_network_contribution_for_payment", "hospitality.link.payment_drawn_on_card", "hospitality.link.payment_for_fraud_assessment", "hospitality.link.payment_for_reservation", "hospitality.link.payment_refunds_payment", "hospitality.link.payout_line_for_payment", "hospitality.link.platform_ledger_line_for_payment", "hospitality.link.rail_instruction_for_payment", "hospitality.link.workflow_run_targets_payment" ] } } ] }, "/v1/object-types/hospitality.payment/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA payment applied to a folio. Settles charges. Refunds are recorded as a **separate negative-amount Payment row** linked to the original settled payment via `payment_refunds_payment` and carrying `payment_kind = refund` per proposal 0019. The original settled Payment row stays immutable — `status = settled` is the evidence that money was captured, and partial-refund / multiple-refund state is derived from the linked refund legs rather than by rewriting the source row.", "operationId": "traverse_hospitality_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.cashier_transaction_mirrors_payment", "hospitality.link.dispute_for_payment", "hospitality.link.folio_has_payment", "hospitality.link.fraud_network_contribution_for_payment", "hospitality.link.payment_drawn_on_card", "hospitality.link.payment_for_fraud_assessment", "hospitality.link.payment_for_reservation", "hospitality.link.payment_refunds_payment", "hospitality.link.payout_line_for_payment", "hospitality.link.platform_ledger_line_for_payment", "hospitality.link.rail_instruction_for_payment", "hospitality.link.workflow_run_targets_payment" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payment:read" ] } ], "summary": "Traverse from Payment", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.payment/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA payment applied to a folio. Settles charges. Refunds are recorded as a **separate negative-amount Payment row** linked to the original settled payment via `payment_refunds_payment` and carrying `payment_kind = refund` per proposal 0019. The original settled Payment row stays immutable — `status = settled` is the evidence that money was captured, and partial-refund / multiple-refund state is derived from the linked refund legs rather than by rewriting the source row.", "operationId": "search_hospitality_payment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "method" }, "type": { "const": "eq" }, "value": { "enum": [ "cash", "credit_card", "debit_card", "bank_transfer", "voucher", "loyalty_points", "direct_billing", "mobile_wallet", "ota_collected", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "received_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "received_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "received_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "pending", "settled", "refunded", "voided", "failed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decision_provider" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decision_provider" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decision_provider" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decision_provider" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decision_provider_case_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decision_provider_case_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decision_provider_case_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decision_provider_case_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "liability_shift_basis" }, "type": { "const": "eq" }, "value": { "enum": [ "three_ds2_authenticated", "provider_guarantee", "none" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_outcome" }, "type": { "const": "eq" }, "value": { "enum": [ "frictionless", "challenge_passed", "challenge_failed", "attempted", "pending_decoupled", "not_applicable" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sca_exemption_claimed" }, "type": { "const": "eq" }, "value": { "enum": [ "none", "low_value", "tra", "mit", "trusted_beneficiary", "secure_corporate" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "review_state" }, "type": { "const": "eq" }, "value": { "enum": [ "not_required", "held", "approved", "declined", "expired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authorisation_expires_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authorisation_expires_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authorisation_expires_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "auth_correlation_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "auth_correlation_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "auth_correlation_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "auth_correlation_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_method_token" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_method_token" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_method_token" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_method_token" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "captured_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "captured_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "captured_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "voided_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "voided_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "voided_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "void_reason" }, "type": { "const": "eq" }, "value": { "enum": [ "duplicate", "fraudulent", "requested_by_customer", "abandoned", "review_declined", "authorisation_expired", "reservation_cancelled", "guest_disputed_pre_arrival", "released_at_departure" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "void_note" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "void_note" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_capture_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_capture_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_capture_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_capture_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_void_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_void_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_void_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_void_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "acquirer_reference_number" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "acquirer_reference_number" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "acquirer_reference_number" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "acquirer_reference_number" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "payment", "deposit", "refund" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refund_requested_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refund_requested_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refund_requested_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refund_resolved_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refund_resolved_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refund_resolved_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refund_reason" }, "type": { "const": "eq" }, "value": { "enum": [ "duplicate", "fraudulent", "requested_by_customer", "reservation_cancelled", "deposit_return", "service_recovery", "overcharge_correction", "no_show_policy_exception", "package_component_refund", "membership_cancellation", "chargeback_prevention", "other", "chargeback_lost" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refund_note" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refund_note" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refund_correlation_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refund_correlation_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refund_correlation_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refund_correlation_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_refund_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_refund_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_refund_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_refund_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refund_trace_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refund_trace_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refund_trace_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refund_trace_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refund_trace_reference_type" }, "type": { "const": "eq" }, "value": { "enum": [ "arn", "stan", "rrn", "psp_generated", "unavailable" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refund_failure_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refund_failure_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refund_failure_reason" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refund_failure_reason" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_decision" }, "type": { "const": "eq" }, "value": { "enum": [ "release", "capture", "keep" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_decided_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_decided_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_decided_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_kept_until" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_kept_until" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_kept_until" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_outcome" }, "type": { "const": "eq" }, "value": { "enum": [ "released", "captured", "lapsed", "unresolved" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_outcome_detail" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_outcome_detail" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_purpose" }, "type": { "const": "eq" }, "value": { "enum": [ "booking", "check_in", "top_up", "re_placement", "incidentals", "no_show", "post_stay", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "processor_fee" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "net_to_hotel" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "platform_fee" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "processor_fee_estimate" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fee_class" }, "type": { "const": "eq" }, "value": { "enum": [ "domestic_standard", "domestic_premium", "regional", "international" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "card_present" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "platform_fee_refunded" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fee_true_up" }, "type": { "const": "eq" }, "value": { "enum": [ "refunded", "not_due", "refused" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fee_true_up_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fee_true_up_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fee_true_up_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fee_true_up_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fee_true_up_detail" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fee_true_up_detail" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fraud_warning_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fraud_warning_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fraud_warning_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fraud_warning_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fraud_warning_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fraud_warning_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fraud_warning_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fraud_warning_type" }, "type": { "const": "eq" }, "value": { "enum": [ "card_never_received", "fraudulent_card_application", "made_with_counterfeit_card", "made_with_lost_card", "made_with_stolen_card", "misc", "unauthorized_use_of_card" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fraud_warning_actionable" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fraud_warning_observed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fraud_warning_observed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fraud_warning_observed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fraud_warning_response" }, "type": { "const": "eq" }, "value": { "enum": [ "hold_voided", "refunded", "desk_review", "not_actionable" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fraud_warning_stay_phase" }, "type": { "const": "eq" }, "value": { "enum": [ "before_arrival", "in_house", "ended", "no_booking" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fraud_warning_detail" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fraud_warning_detail" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "method", "received_at", "reference", "status", "decision_provider", "decision_provider_case_id", "liability_shift_basis", "authentication_outcome", "sca_exemption_claimed", "review_state", "authorisation_expires_at", "auth_correlation_id", "payment_method_token", "captured_at", "voided_at", "void_reason", "void_note", "psp_capture_reference", "psp_void_reference", "acquirer_reference_number", "payment_kind", "refund_requested_at", "refund_resolved_at", "refund_reason", "refund_note", "refund_correlation_id", "psp_refund_reference", "refund_trace_reference", "refund_trace_reference_type", "refund_failure_reason", "external_ref", "hold_decision", "hold_decided_at", "hold_kept_until", "hold_outcome", "hold_outcome_detail", "hold_purpose", "fee_class", "fee_true_up", "fee_true_up_reference", "fee_true_up_detail", "fraud_warning_reference", "fraud_warning_at", "fraud_warning_type", "fraud_warning_observed_at", "fraud_warning_response", "fraud_warning_stay_phase", "fraud_warning_detail" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment" }, "properties": { "additionalProperties": false, "properties": { "acquirer_reference_number": { "title": "23-digit ARN (Acquirer Reference Number) assigned post-clearing. The cross-network join key for chargeback investigation; load-bearing at dispute time. Often unavailable at capture time (lands hours later via PSP reconciliation report); populated as a follow-up enrichment when present. Mastercard Banknet Reference and Visa Transaction Identifier (TID, DE 62.2) network references are deferred to a structured sub-object per proposal 0018 §10.2.", "type": "string" }, "amount": { "description": "Amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment amount", "type": "object" }, "auth_correlation_id": { "title": "Host's PSP authorisation reference (Stripe payment_intent_id, Adyen pspReference, Worldpay transactionReference). Per-payment join key for reconciling PSP-side records with the Aerandil audit trail.", "type": "string" }, "authentication_outcome": { "enum": [ "frictionless", "challenge_passed", "challenge_failed", "attempted", "pending_decoupled", "not_applicable" ], "title": "EMV 3DS 2.2 authentication result on this authorisation. `pending_decoupled` covers the EMVCo 2.2 decoupled async flow (up to 7 days for the result to land).", "type": "string" }, "authorisation_expires_at": { "format": "date-time", "title": "Scheme's authorisation-validity window (Visa 30 days for MCC 3501-7011 lodging, Mastercard 7 days final auth / 30 days pre-auth, Amex 7 days). Set by the host at authorisation time per their PSP integration; `authorisation_expiry_beyond_scheme_window` soft-warns at > 30 days.", "type": "string" }, "captured_at": { "format": "date-time", "title": "Wall-clock timestamp when the capture transitioned `status = pending → settled` via `capture_authorised_charge`. Distinct from `received_at` (set at authorisation time). Null for rows that reached `settled` via the direct-settle `apply_payment` path or historical rows pre-dating proposal 0018.", "type": "string" }, "card_present": { "title": "Whether the payment was priced as card-present (a terminal) rather than online", "type": "boolean" }, "decision_provider": { "title": "Fraud-decision vendor (denormalised from the gating assessment's vendor_id; cohort key for chargeback-rate analytics per fraud-vendor)", "type": "string" }, "decision_provider_case_id": { "title": "Vendor's case / decision identifier (Stripe Radar evaluation id, Adyen case ref, Riskified decision id, Forter forterDecisionId, Signifyd case id, Sift event id, Kount tran id). The chargeback-dispute exhibit pointer.", "type": "string" }, "external_ref": { "title": "Source-system key for connector-landed payments", "type": "string" }, "fee_class": { "enum": [ "domestic_standard", "domestic_premium", "regional", "international" ], "title": "The card's class the platform's fee was priced by — `domestic_standard`, `domestic_premium`, `regional` or `international`, read from the card's issuing country against the account's", "type": "string" }, "fee_true_up": { "description": "Set by `record_page_fee` on a payment a hosted page took: `refunded` (the difference to the card's own class was refunded), `not_due` (nothing to give back), `refused` (the processor refused the refund; the hotel paid the ceiling, `fee_true_up_detail` says why, and the operator's variance shows it). Absent on every other payment.", "enum": [ "refunded", "not_due", "refused" ], "title": "How the page's fee came out", "type": "string" }, "fee_true_up_detail": { "title": "The processor's words for a refused fee refund", "type": "string" }, "fee_true_up_reference": { "description": "The processor's id for the application-fee refund the page's true-up made (Stripe `fr_…`).", "title": "The processor's refund of the platform's fee", "type": "string" }, "fraud_warning_actionable": { "title": "Whether the processor still calls the warning actionable — not yet disputed and not refunded in full", "type": "boolean" }, "fraud_warning_at": { "description": "Set when an issuer flags this payment as suspected fraud (an early fraud warning: Visa's TC40, Mastercard's SAFE report). About 40% of Visa and Mastercard warnings become fraud disputes when the charge is not refunded, and Visa's VAMP counts the warning itself whatever happens next. Absent on a payment no issuer has flagged.", "format": "date-time", "title": "When the issuer's early fraud warning was raised", "type": "string" }, "fraud_warning_detail": { "title": "Why the card rail responded as it did, in words", "type": "string" }, "fraud_warning_observed_at": { "format": "date-time", "title": "The processor's time of the latest report about the warning on file — the watermark an out-of-order report is checked against", "type": "string" }, "fraud_warning_reference": { "description": "Stripe's `issfr_…` for the early fraud warning an issuer raised on this payment's charge — the join key for every later report about the same warning.", "title": "The processor's id for the issuer's early fraud warning", "type": "string" }, "fraud_warning_response": { "description": "Decided once, from the stay, when the warning first arrives: `hold_voided` (an uncaptured hold released before capture — the cardholder cannot dispute it), `refunded` (a captured line after the stay at or under the house's ceiling, refunded in full), `desk_review` (a deposit before arrival, a stay in house, a line above the ceiling, or a release or refund the ledger refused — a person decides), `not_actionable` (already disputed or refunded, or nothing left to act on).", "enum": [ "hold_voided", "refunded", "desk_review", "not_actionable" ], "title": "What the card rail did about the warning", "type": "string" }, "fraud_warning_stay_phase": { "enum": [ "before_arrival", "in_house", "ended", "no_booking" ], "title": "Where the booking stood when the warning arrived", "type": "string" }, "fraud_warning_type": { "enum": [ "card_never_received", "fraudulent_card_application", "made_with_counterfeit_card", "made_with_lost_card", "made_with_stolen_card", "misc", "unauthorized_use_of_card" ], "title": "The kind of fraud the issuer labelled", "type": "string" }, "hold_decided_at": { "format": "date-time", "title": "When check-out decided this hold", "type": "string" }, "hold_decision": { "description": "Set on a pending card hold when its stay checks out: `release` (the card rail voids it), `capture` (the bill still owed money — the rail takes that from the hold, which lets the rest go), or `keep` (the house's post-stay window is on; the hold stays for charges found after departure until `hold_kept_until`). Absent on a hold no departure has decided.", "enum": [ "release", "capture", "keep" ], "title": "What check-out decided for this hold", "type": "string" }, "hold_kept_until": { "format": "date-time", "title": "Until when a kept hold is kept for post-stay charges", "type": "string" }, "hold_outcome": { "enum": [ "released", "captured", "lapsed", "unresolved" ], "title": "What became of a decided hold at the processor: released, captured, lapsed, or unresolved (still pending; the desk settles it)", "type": "string" }, "hold_outcome_detail": { "title": "The processor's words when a hold's outcome is unresolved", "type": "string" }, "hold_purpose": { "description": "Set on a card hold when it is placed: `booking` (the guarantee before arrival — the pay page's hold, or a desk hold on the booking's own account), `check_in` (the desk's hold on the stay's folio), `top_up`, `re_placement` (the card rail renewing a booking hold before the issuer lapses it), `incidentals`, `no_show`, `post_stay`, or `other`. A hold carried from the booking onto the stay at check-in keeps `booking`. Absent on a payment taken in one step.", "enum": [ "booking", "check_in", "top_up", "re_placement", "incidentals", "no_show", "post_stay", "other" ], "title": "Why this hold was placed", "type": "string" }, "id": { "title": "Payment id", "type": "string" }, "liability_shift_basis": { "enum": [ "three_ds2_authenticated", "provider_guarantee", "none" ], "title": "Why a chargeback would shift away from the merchant. Per-decision, not per-vendor.", "type": "string" }, "method": { "enum": [ "cash", "credit_card", "debit_card", "bank_transfer", "voucher", "loyalty_points", "direct_billing", "mobile_wallet", "ota_collected", "other" ], "title": "Method", "type": "string" }, "net_to_hotel": { "description": "What the transfer to the hotel carried less the application fee the platform took back, net of any transfer reversal or fee refund a refund made — the platform's balance transactions for the payment, folded by `record_processor_fee`. Equals the hotel's own payout line for the charge (amount less fee). Chargeback movements are the case's (`platform_dispute_cost`), not counted here.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment net to hotel", "type": "object" }, "payment_kind": { "enum": [ "payment", "deposit", "refund" ], "title": "Ledger-leg discriminator. `payment` is the original payment authorisation / settlement; `deposit` is a pre-arrival payment taken by `record_deposit_payment` (a refund settling against it is recorded on the booking as deposit returned); `refund` is a negative-amount leg created by `refund_payment` and linked to the original via `payment_refunds_payment`. Unset legacy rows are interpreted as `payment` by handler-level coherence rules. The companion `void_authorisation` action (proposal 0018) is gated to `payment_kind = payment` rows by the `void_requires_payment_kind_payment` validator so refund legs resolve through `resolve_payment_refund` instead.", "type": "string" }, "payment_method_token": { "title": "PSP-issued opaque token referencing the cardholder data in the operator's PSP / vault. Must NOT be a Luhn-passing 13-19-digit sequence — `payment_token_no_pan_shape` hard validator enforces PCI-DSS 4.0 (PAN never enters Aerandil).", "type": "string" }, "platform_fee": { "description": "The platform's fee on this card payment as the account's fee schedule priced it for the card's class (`fee_class`, `card_present`) — the processor's `application_fee_amount`, set when the money was taken, on what was taken. Absent on a payment that settled to the platform's own account.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment platform fee", "type": "object" }, "platform_fee_refunded": { "description": "What of the platform's fee the card rail refunded to the hotel when the hosted page this payment came from completed: the link fixed its fee at the account's dearest card class (`payment_request.page_fee_ceiling`), and the difference to the class of the card the guest paid with went back as an application-fee refund. `platform_fee` is what the platform kept. Zero when nothing was due or the refund was refused (`fee_true_up`). In the payment's currency.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment platform fee refunded", "type": "object" }, "processor_fee": { "description": "Stripe's actual processing fee on the payment's charge, read off the platform's balance transaction for it (its `fee`; a partial capture's reversal line counted in) by `record_processor_fee`. On a destination charge the fee is the platform's, recouped through the application fee — `processor_fee` beside `processor_fee_estimate` is the variance the pricing decision reports per account per month; the hotel is never trued up. In the platform's balance currency.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment processor fee", "type": "object" }, "processor_fee_estimate": { "description": "The processor's published rate for the card's class on what was taken (its conversion fee added when the charge's currency is not the schedule's) — the estimate `processor_fee` is read back against. In the charge's currency.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment processor fee estimate", "type": "object" }, "psp_capture_reference": { "title": "PSP-issued reference to the capture leg, distinct from the auth's `auth_correlation_id`. Stripe `latest_charge.id`; Adyen `/captures` response `pspReference` (a new pspRef distinct from the auth pspRef); Checkout.com `action_id`; Cybersource capture `id`. Per-payment join key for reconciliation with PSP-side records.", "type": "string" }, "psp_refund_reference": { "title": "PSP-issued refund reference: Stripe `refund.id`, Adyen refund response `pspReference` (a new pspRef distinct from the capture pspRef), Checkout.com refund `action_id`, Worldpay refund event link / reference, Braintree refund transaction id, Cybersource credit id, Mews `RefundId`. Per-leg join key for reconciliation with PSP-side refund records; may be unavailable at request time and populated later by `resolve_payment_refund`.", "type": "string" }, "psp_void_reference": { "title": "PSP-issued reference to the void / cancel / reversal leg. Stripe PaymentIntent state-transition event id; Adyen `/cancels` or `/reversals` response `pspReference`; Checkout.com `action_id`.", "type": "string" }, "received_at": { "format": "date-time", "title": "Received at", "type": "string" }, "reference": { "title": "Reference", "type": "string" }, "refund_correlation_id": { "title": "Host-side idempotency / reconciliation key for the refund request. Required by `refund_payment` because two legitimate same-amount partial refunds with the same reason can occur against one payment — amount + reason alone cannot key the idempotency cache. If the PSP refund reference is already known synchronously, the host may reuse it here; otherwise the host generates a stable correlation id and stores the later `psp_refund_reference` on resolution.", "type": "string" }, "refund_failure_reason": { "title": "PSP / network reason for a failed or voided refund leg (e.g. `declined`, `insufficient_funds`, closed account, processor settlement decline, operator cancellation). Required at the handler level when `resolve_payment_refund(refund_status = failed)`; optional otherwise. Free-form because PSPs do not converge on a closed taxonomy of refund-failure codes — Stripe, Adyen, Braintree, and Cybersource each expose their own error vocabulary that the host typically pastes through verbatim.", "type": "string" }, "refund_note": { "title": "Free-form human-readable colour on a refund leg, complementing the closed `refund_reason` enum. Required when `refund_reason = other`; optional otherwise. Capped at 1024 characters at the handler level.", "type": "string" }, "refund_reason": { "enum": [ "duplicate", "fraudulent", "requested_by_customer", "reservation_cancelled", "deposit_return", "service_recovery", "overcharge_correction", "no_show_policy_exception", "package_component_refund", "membership_cancellation", "chargeback_prevention", "other", "chargeback_lost" ], "title": "Closed reason taxonomy on a refund leg. Stripe / Adyen canonical three (`duplicate`, `fraudulent`, `requested_by_customer`) plus nine Aerandil-domain hospitality reasons (`reservation_cancelled`, `deposit_return`, `service_recovery`, `overcharge_correction`, `no_show_policy_exception`, `package_component_refund`, `membership_cancellation`, `chargeback_prevention`, `other`), and `chargeback_lost` — the leg `record_payment_dispute` writes when a chargeback is lost, which `refund_payment` never accepts. Required at the handler level for `refund_payment`; optional on the property because third-party importers may write refund rows without one. `other` requires `refund_note` per the `refund_other_requires_note` validator.", "type": "string" }, "refund_requested_at": { "format": "date-time", "title": "Timestamp when the host recorded the refund request / PSP accepted the refund request. For refund rows, the required `received_at` mirrors this timestamp so legacy ledger queries that group by `received_at` continue to work without per-leg date logic.", "type": "string" }, "refund_resolved_at": { "format": "date-time", "title": "Timestamp when the refund leg reached a terminal outcome (`status = refunded`, `failed`, or `voided`). Null while the leg is `pending`. Populated by `resolve_payment_refund`, or by `refund_payment` when `refund_initial_status = refunded` for a synchronously-confirmed refund.", "type": "string" }, "refund_trace_reference": { "title": "Downstream trace reference the cardholder can take to their bank when the refund is not visible on the card. Stripe documents ARN / STAN / RRN for this purpose; often lands days after the refund request via PSP reconciliation. Typed by `refund_trace_reference_type` so the operator knows which network reference to quote — Visa ARN, network STAN, network RRN, or a PSP-internal trace handle.", "type": "string" }, "refund_trace_reference_type": { "enum": [ "arn", "stan", "rrn", "psp_generated", "unavailable" ], "title": "Type tag on `refund_trace_reference`. `arn` (23-digit Acquirer Reference Number); `stan` (System Trace Audit Number); `rrn` (Retrieval Reference Number); `psp_generated` (PSP-internal handle when the network reference is not yet exposed); `unavailable` (same-day reversals and pre-clearing refunds may have no traceable network reference at all). Kept separate from 0018's `acquirer_reference_number` because refund reversals can lack an ARN while still having STAN / RRN evidence; `refund_trace_reference_type_coherence` enforces the reference / type pairing.", "type": "string" }, "review_state": { "enum": [ "not_required", "held", "approved", "declined", "expired" ], "title": "Post-network review-hold state. `not_required` for direct-capture flows; `held` for manual_capture_after_review with a held_for_review outcome; `approved` / `declined` / `expired` are terminal states transitioned atomically by the `capture_authorised_charge` and `void_authorisation` companion actions (proposals 0017 §6.2 and 0018 §6).", "type": "string" }, "sca_exemption_claimed": { "enum": [ "none", "low_value", "tra", "mit", "trusted_beneficiary", "secure_corporate" ], "title": "PSD2 SCA exemption claimed by the host at authorisation time. The PSP is the source of truth on whether the exemption was actually granted; Aerandil records the claim plus the amount-ceiling sanity validators.", "type": "string" }, "status": { "enum": [ "pending", "settled", "refunded", "voided", "failed" ], "title": "Status", "type": "string" }, "void_note": { "title": "Free-form human-readable colour on a voided payment, complementing the closed `void_reason` enum. Mirrors Adyen's open `reference` field pattern. Capped at 1024 characters at the handler level.", "type": "string" }, "void_reason": { "enum": [ "duplicate", "fraudulent", "requested_by_customer", "abandoned", "review_declined", "authorisation_expired", "reservation_cancelled", "guest_disputed_pre_arrival", "released_at_departure" ], "title": "Closed reason taxonomy on a voided payment. Stripe-aligned canonical four (`duplicate`, `fraudulent`, `requested_by_customer`, `abandoned`) plus Aerandil-domain hospitality four (`review_declined`, `authorisation_expired`, `reservation_cancelled`, `guest_disputed_pre_arrival`). Required at the handler level for `void_authorisation`; optional on the property because third-party importers may write voided rows without one. PSP-side capture-failure events (Adyen `CAPTURE_FAILED`, Checkout.com capture-declined) are deliberately excluded — see proposal 0018 §1 and §10.1.", "type": "string" }, "voided_at": { "format": "date-time", "title": "Wall-clock timestamp when the void transitioned `status = pending → voided` via `void_authorisation`. Populated by the void handler; null otherwise.", "type": "string" } }, "required": [ "id", "amount", "method", "received_at", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payment:read" ] } ], "summary": "Search Payment", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.payment_card/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA tokenised card the property may draw on later — the card-on-file record behind a no-show fee, a post-departure incidental, or a check-in guarantee. Holds the PSP's token and the fragments that identify the card to a human (scheme, last four, expiry); never a PAN. Binds to the person who holds it, or — for an OTA virtual card, which has no cardholder — to the reservation it was minted for; a pay page's card whose payer is not the booking's guest binds to that booking alone.", "operationId": "get_hospitality_payment_card", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment_card" }, "properties": { "additionalProperties": false, "properties": { "activation_at": { "format": "date-time", "title": "The instant the house's day reaches `activation_date` (its local midnight) — what the charge automation compares with the clock", "type": "string" }, "activation_charge_amount": { "description": "What the activation charge asked the card for", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment card activation charge amount", "type": "object" }, "activation_charge_attempts": { "title": "How many times the activation charge has been asked for", "type": "integer" }, "activation_charge_refusal": { "title": "Why the activation charge did not happen — the desk's to resolve", "type": "string" }, "activation_charge_requested_at": { "format": "date-time", "title": "When the activation charge was last asked for", "type": "string" }, "activation_charge_status": { "enum": [ "requested", "charged", "refused" ], "title": "Where the activation charge stands: `requested` (the card rail has it), `charged` (the payment is on the booking's account) or `refused` (no charge, and why in `activation_charge_refusal`)", "type": "string" }, "activation_charged_at": { "format": "date-time", "title": "When the processor took the activation charge", "type": "string" }, "activation_date": { "format": "date", "title": "For a `virtual` card, the first day the channel lets the house charge it, in the house's calendar", "type": "string" }, "activation_payment_id": { "format": "uuid", "title": "The payment the activation charge posted to the booking's account", "type": "string", "x-aerandil-references": "hospitality.payment" }, "brand": { "enum": [ "visa", "mastercard", "amex", "discover", "diners", "jcb", "unionpay", "cartes_bancaires", "eftpos_au", "interac", "maestro", "unknown" ], "title": "Card scheme", "type": "string" }, "capture_kind": { "enum": [ "terminal", "keyed_by_staff", "guest_device", "imported" ], "title": "How the card's details reached the PSP. Decides card-present interchange, who carries chargeback liability, and whether the cardholder's presence satisfied SCA — not a provenance note.", "type": "string" }, "card_format": { "enum": [ "physical", "virtual" ], "title": "Whether the number belongs to a person (`physical`) or to one booking (`virtual` — an OTA-issued single-stay card).", "type": "string" }, "cardholder_name": { "title": "The payer's name as the hosted page took it, on a page's card whose payer is not the booking's guest — such a card has no cardholder person and binds to the booking alone", "type": "string" }, "expiry_month": { "title": "Expiry month, 1-12", "type": "integer" }, "expiry_year": { "title": "Expiry year, four digits", "type": "integer" }, "funded_amount": { "description": "What the channel loaded the virtual card with — the most the house may charge it", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment card funded amount", "type": "object" }, "funding": { "enum": [ "credit", "debit", "prepaid", "unknown" ], "title": "What the card draws on, as the scheme reports it. The host maps this onto `Payment.method` at posting time rather than the card carrying the ledger's word for it.", "type": "string" }, "id": { "title": "Card record id", "type": "string" }, "issuing_country": { "title": "Card's issuing country (ISO 3166-1 alpha-2). Drives interchange and the domestic/cross-border SCA question.", "type": "string" }, "last4": { "title": "Last four glyphs of the card number — the maximum fragment stored, never the full number. For a wallet card this is the device account number, not the funding card's.", "type": "string" }, "last_used_at": { "format": "date-time", "title": "When a payment was last drawn on this card. Drives the desk's ordering of a guest's cards, and the dormancy half of the retention argument.", "type": "string" }, "merchant_account_ref": { "format": "uuid", "title": "The merchant account — the merchant of record — the card's stored-credential agreement is with: the one whose PSP Customer the card hangs off and the only one that may draw on it (2026-10-22). Absent for a card kept on the platform's own account and for a channel's virtual card.", "type": "string", "x-aerandil-references": "hospitality.merchant_account" }, "network_fingerprint": { "title": "PSP-issued stable identifier for the underlying card number — the same physical card presented by two guests carries the same value. Not derivable back to a PAN, but it *is* a cross-profile card identity, so it carries the token marking: a fraud cohort is a legitimate use, a curiosity is not.", "type": "string" }, "off_session_consent": { "title": "True when the cardholder authenticated with the stated intent that the property may charge this card later. The SCA precondition for a no-show fee or a post-departure incidental: a card saved without it may simply be declined at the moment the guest is unreachable, so the fact is recorded at capture rather than assumed at charge time.", "type": "boolean" }, "provider": { "title": "PSP that holds the card (`stripe`, `adyen`). Free-form for the same reason `decision_provider` is: the set of processors is the operator's, not ours.", "type": "string" }, "provider_card_ref": { "title": "The PSP's token for this card (Stripe PaymentMethod id, Adyen recurringDetailReference). The only thing that can actually move money, and the reason this object exists — `payment_token_no_pan_shape` refuses anything Luhn-shaped here exactly as it does on `Payment.payment_method_token`.", "type": "string" }, "provider_customer_ref": { "title": "The PSP-side customer the card is attached to (Stripe Customer id). Required by the processor before a card can be charged off-session; distinct from `hospitality.person`, which is ours.", "type": "string" }, "retain_until": { "format": "date", "title": "Storage-limitation clock the pruner honours — the same discipline `guest_id_document` carries. A card kept past the purpose that justified keeping it is a finding in any PCI or GDPR review.", "type": "string" }, "source": { "enum": [ "guest_device_page" ], "title": "Where the card's off-session consent was given, when narrower than its cardholder's: `guest_device_page` — on a booking's pay page, whose terms cover the bookings the card is bound to and not the cardholder's others. Unset for a card the desk, an import or a channel stored.", "type": "string" }, "status": { "enum": [ "active", "expired", "removed" ], "title": "Usability: `active`, `expired`, or `removed`. Never deleted — a card that backed a settled payment is chargeback evidence.", "type": "string" }, "stored_at": { "format": "date-time", "title": "When the card was recorded", "type": "string" }, "wallet": { "enum": [ "apple_pay", "google_pay", "samsung_pay", "link", "click_to_pay", "other" ], "title": "The wallet the card was presented through, when it was. Unset means presented directly.", "type": "string" } }, "required": [ "id", "provider", "brand", "last4", "expiry_month", "expiry_year", "capture_kind", "card_format", "off_session_consent", "status", "stored_at", "retain_until" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payment_card:read" ] } ], "summary": "Read Payment card", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.payment_card/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA tokenised card the property may draw on later — the card-on-file record behind a no-show fee, a post-departure incidental, or a check-in guarantee. Holds the PSP's token and the fragments that identify the card to a human (scheme, last four, expiry); never a PAN. Binds to the person who holds it, or — for an OTA virtual card, which has no cardholder — to the reservation it was minted for; a pay page's card whose payer is not the booking's guest binds to that booking alone.", "operationId": "get_hospitality_payment_card_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.payment_card" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payment_card:read" ] } ], "summary": "Read Payment card as of a watermark", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.payment_card/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA tokenised card the property may draw on later — the card-on-file record behind a no-show fee, a post-departure incidental, or a check-in guarantee. Holds the PSP's token and the fragments that identify the card to a human (scheme, last four, expiry); never a PAN. Binds to the person who holds it, or — for an OTA virtual card, which has no cardholder — to the reservation it was minted for; a pay page's card whose payer is not the booking's guest binds to that booking alone.", "operationId": "list_links_hospitality_payment_card", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payment_card:read" ] } ], "summary": "List links of Payment card", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.payment_card_for_person", "hospitality.link.payment_card_for_reservation", "hospitality.link.payment_drawn_on_card" ] } } ] }, "/v1/object-types/hospitality.payment_card/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA tokenised card the property may draw on later — the card-on-file record behind a no-show fee, a post-departure incidental, or a check-in guarantee. Holds the PSP's token and the fragments that identify the card to a human (scheme, last four, expiry); never a PAN. Binds to the person who holds it, or — for an OTA virtual card, which has no cardholder — to the reservation it was minted for; a pay page's card whose payer is not the booking's guest binds to that booking alone.", "operationId": "traverse_hospitality_payment_card", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.payment_card_for_person", "hospitality.link.payment_card_for_reservation", "hospitality.link.payment_drawn_on_card" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payment_card:read" ] } ], "summary": "Traverse from Payment card", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.payment_card/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA tokenised card the property may draw on later — the card-on-file record behind a no-show fee, a post-departure incidental, or a check-in guarantee. Holds the PSP's token and the fragments that identify the card to a human (scheme, last four, expiry); never a PAN. Binds to the person who holds it, or — for an OTA virtual card, which has no cardholder — to the reservation it was minted for; a pay page's card whose payer is not the booking's guest binds to that booking alone.", "operationId": "search_hospitality_payment_card", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider_card_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider_card_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider_card_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider_card_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider_customer_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider_customer_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider_customer_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "provider_customer_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "merchant_account_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.merchant_account" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "network_fingerprint" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "network_fingerprint" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "network_fingerprint" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "network_fingerprint" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "brand" }, "type": { "const": "eq" }, "value": { "enum": [ "visa", "mastercard", "amex", "discover", "diners", "jcb", "unionpay", "cartes_bancaires", "eftpos_au", "interac", "maestro", "unknown" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last4" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last4" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last4" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last4" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expiry_month" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expiry_month" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expiry_month" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expiry_year" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expiry_year" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expiry_year" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "funding" }, "type": { "const": "eq" }, "value": { "enum": [ "credit", "debit", "prepaid", "unknown" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issuing_country" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issuing_country" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issuing_country" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issuing_country" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "capture_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "terminal", "keyed_by_staff", "guest_device", "imported" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "card_format" }, "type": { "const": "eq" }, "value": { "enum": [ "physical", "virtual" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "wallet" }, "type": { "const": "eq" }, "value": { "enum": [ "apple_pay", "google_pay", "samsung_pay", "link", "click_to_pay", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "off_session_consent" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "expired", "removed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "stored_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "stored_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "stored_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_used_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_used_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_used_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retain_until" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retain_until" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retain_until" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "activation_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "activation_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "activation_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "activation_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "activation_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "activation_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "funded_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "activation_charge_status" }, "type": { "const": "eq" }, "value": { "enum": [ "requested", "charged", "refused" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "activation_charge_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "activation_charge_attempts" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "activation_charge_attempts" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "activation_charge_attempts" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "activation_charge_requested_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "activation_charge_requested_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "activation_charge_requested_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "activation_charged_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "activation_charged_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "activation_charged_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "activation_payment_id" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.payment" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "activation_charge_refusal" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "activation_charge_refusal" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source" }, "type": { "const": "eq" }, "value": { "enum": [ "guest_device_page" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cardholder_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cardholder_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cardholder_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cardholder_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "provider", "provider_card_ref", "provider_customer_ref", "network_fingerprint", "brand", "last4", "expiry_month", "expiry_year", "funding", "issuing_country", "capture_kind", "card_format", "wallet", "status", "stored_at", "last_used_at", "retain_until", "activation_date", "activation_at", "activation_charge_status", "activation_charge_attempts", "activation_charge_requested_at", "activation_charged_at", "activation_charge_refusal", "source", "cardholder_name" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment_card" }, "properties": { "additionalProperties": false, "properties": { "activation_at": { "format": "date-time", "title": "The instant the house's day reaches `activation_date` (its local midnight) — what the charge automation compares with the clock", "type": "string" }, "activation_charge_amount": { "description": "What the activation charge asked the card for", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment card activation charge amount", "type": "object" }, "activation_charge_attempts": { "title": "How many times the activation charge has been asked for", "type": "integer" }, "activation_charge_refusal": { "title": "Why the activation charge did not happen — the desk's to resolve", "type": "string" }, "activation_charge_requested_at": { "format": "date-time", "title": "When the activation charge was last asked for", "type": "string" }, "activation_charge_status": { "enum": [ "requested", "charged", "refused" ], "title": "Where the activation charge stands: `requested` (the card rail has it), `charged` (the payment is on the booking's account) or `refused` (no charge, and why in `activation_charge_refusal`)", "type": "string" }, "activation_charged_at": { "format": "date-time", "title": "When the processor took the activation charge", "type": "string" }, "activation_date": { "format": "date", "title": "For a `virtual` card, the first day the channel lets the house charge it, in the house's calendar", "type": "string" }, "activation_payment_id": { "format": "uuid", "title": "The payment the activation charge posted to the booking's account", "type": "string", "x-aerandil-references": "hospitality.payment" }, "brand": { "enum": [ "visa", "mastercard", "amex", "discover", "diners", "jcb", "unionpay", "cartes_bancaires", "eftpos_au", "interac", "maestro", "unknown" ], "title": "Card scheme", "type": "string" }, "capture_kind": { "enum": [ "terminal", "keyed_by_staff", "guest_device", "imported" ], "title": "How the card's details reached the PSP. Decides card-present interchange, who carries chargeback liability, and whether the cardholder's presence satisfied SCA — not a provenance note.", "type": "string" }, "card_format": { "enum": [ "physical", "virtual" ], "title": "Whether the number belongs to a person (`physical`) or to one booking (`virtual` — an OTA-issued single-stay card).", "type": "string" }, "cardholder_name": { "title": "The payer's name as the hosted page took it, on a page's card whose payer is not the booking's guest — such a card has no cardholder person and binds to the booking alone", "type": "string" }, "expiry_month": { "title": "Expiry month, 1-12", "type": "integer" }, "expiry_year": { "title": "Expiry year, four digits", "type": "integer" }, "funded_amount": { "description": "What the channel loaded the virtual card with — the most the house may charge it", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment card funded amount", "type": "object" }, "funding": { "enum": [ "credit", "debit", "prepaid", "unknown" ], "title": "What the card draws on, as the scheme reports it. The host maps this onto `Payment.method` at posting time rather than the card carrying the ledger's word for it.", "type": "string" }, "id": { "title": "Card record id", "type": "string" }, "issuing_country": { "title": "Card's issuing country (ISO 3166-1 alpha-2). Drives interchange and the domestic/cross-border SCA question.", "type": "string" }, "last4": { "title": "Last four glyphs of the card number — the maximum fragment stored, never the full number. For a wallet card this is the device account number, not the funding card's.", "type": "string" }, "last_used_at": { "format": "date-time", "title": "When a payment was last drawn on this card. Drives the desk's ordering of a guest's cards, and the dormancy half of the retention argument.", "type": "string" }, "merchant_account_ref": { "format": "uuid", "title": "The merchant account — the merchant of record — the card's stored-credential agreement is with: the one whose PSP Customer the card hangs off and the only one that may draw on it (2026-10-22). Absent for a card kept on the platform's own account and for a channel's virtual card.", "type": "string", "x-aerandil-references": "hospitality.merchant_account" }, "network_fingerprint": { "title": "PSP-issued stable identifier for the underlying card number — the same physical card presented by two guests carries the same value. Not derivable back to a PAN, but it *is* a cross-profile card identity, so it carries the token marking: a fraud cohort is a legitimate use, a curiosity is not.", "type": "string" }, "off_session_consent": { "title": "True when the cardholder authenticated with the stated intent that the property may charge this card later. The SCA precondition for a no-show fee or a post-departure incidental: a card saved without it may simply be declined at the moment the guest is unreachable, so the fact is recorded at capture rather than assumed at charge time.", "type": "boolean" }, "provider": { "title": "PSP that holds the card (`stripe`, `adyen`). Free-form for the same reason `decision_provider` is: the set of processors is the operator's, not ours.", "type": "string" }, "provider_card_ref": { "title": "The PSP's token for this card (Stripe PaymentMethod id, Adyen recurringDetailReference). The only thing that can actually move money, and the reason this object exists — `payment_token_no_pan_shape` refuses anything Luhn-shaped here exactly as it does on `Payment.payment_method_token`.", "type": "string" }, "provider_customer_ref": { "title": "The PSP-side customer the card is attached to (Stripe Customer id). Required by the processor before a card can be charged off-session; distinct from `hospitality.person`, which is ours.", "type": "string" }, "retain_until": { "format": "date", "title": "Storage-limitation clock the pruner honours — the same discipline `guest_id_document` carries. A card kept past the purpose that justified keeping it is a finding in any PCI or GDPR review.", "type": "string" }, "source": { "enum": [ "guest_device_page" ], "title": "Where the card's off-session consent was given, when narrower than its cardholder's: `guest_device_page` — on a booking's pay page, whose terms cover the bookings the card is bound to and not the cardholder's others. Unset for a card the desk, an import or a channel stored.", "type": "string" }, "status": { "enum": [ "active", "expired", "removed" ], "title": "Usability: `active`, `expired`, or `removed`. Never deleted — a card that backed a settled payment is chargeback evidence.", "type": "string" }, "stored_at": { "format": "date-time", "title": "When the card was recorded", "type": "string" }, "wallet": { "enum": [ "apple_pay", "google_pay", "samsung_pay", "link", "click_to_pay", "other" ], "title": "The wallet the card was presented through, when it was. Unset means presented directly.", "type": "string" } }, "required": [ "id", "provider", "brand", "last4", "expiry_month", "expiry_year", "capture_kind", "card_format", "off_session_consent", "status", "stored_at", "retain_until" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payment_card:read" ] } ], "summary": "Search Payment card", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.payment_dispute/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA chargeback or pre-dispute inquiry raised against a settled payment. Mirrored from the processor, which mirrors the card network — the kernel never decides a dispute's state, it records one. The money moves at `opened_at` (withdrawn) and again at `closed_at` if the case is won; between those the funds are held by the network and the payment cannot be refunded outside the dispute process.", "operationId": "get_hospitality_payment_dispute", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment_dispute" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "Disputed amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute amount", "type": "object" }, "card_brand": { "title": "The disputed card's brand as the processor reports it on the case (Stripe `payment_method_details.card.brand`) — what the evidence's page limit is read by when the payment names no stored card", "type": "string" }, "charge_still_refundable": { "title": "Whether the disputed payment can still be refunded. False for most open chargebacks: refunding outside the dispute process is blocked, and doing it anyway pays the cardholder twice.", "type": "boolean" }, "closed_at": { "format": "date-time", "title": "Closed at", "type": "string" }, "dispute_fee": { "description": "What the processor charged for the case, net of any fee it returned — Stripe's dispute fee, read off the dispute's balance transactions (the countered fee comes back on a win; the received fee never does). On a hotel's own account it is passed to the hotel at cost when the case is lost — its own transfer reversal beside the disputed amount, and what the transfer cannot carry debited from the hotel's Stripe balance; `dispute_fee_recovered` says what was. On the platform's, it stays the platform's.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute dispute fee", "type": "object" }, "dispute_fee_attempt_open_at": { "format": "date-time", "title": "Set while a retry is open — written before the processor is asked, cleared when its outcome is recorded; an open retry is asked again under the same key", "type": "string" }, "dispute_fee_attempts": { "title": "How many retries of an owed dispute fee the card rail has opened (the debit at the chargeback's close is not counted)", "type": "integer" }, "dispute_fee_last_attempt_at": { "format": "date-time", "title": "When the card rail last retried the owed fee", "type": "string" }, "dispute_fee_owed": { "description": "What of the dispute fee could not be taken yet — present only while some is owed", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute dispute fee owed", "type": "object" }, "dispute_fee_recovered": { "description": "What of the dispute fee the hotel was charged: off its transfer and debited from its Stripe balance", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute dispute fee recovered", "type": "object" }, "dispute_fee_recovery": { "enum": [ "recovered", "owed", "other_currency", "written_off", "needs_review", "returned", "waived" ], "title": "recovered, owed, other_currency (never converted by guesswork), written_off (the platform carries it after the last retry), needs_review (a retry whose outcome could not be read back from the processor: parked for a person, never retried blind), or returned (the case was won after it was lost: the fee is no longer the hotel's, and what it paid goes back with the disputed amount — see `hotel_reinstatement`), or waived (move 12: the case was certified for the dispute-fee waiver when its evidence was submitted, so the platform did not pass the network's fees through — `dispute_fee_waived`; never a payment to the hotel)", "type": "string" }, "dispute_fee_recovery_detail": { "title": "Stripe's words for why the rest was not taken", "type": "string" }, "dispute_fee_review_note": { "title": "What the person who settled the parked fee found", "type": "string" }, "dispute_fee_review_reference": { "title": "The processor's debit a person found when settling a fee the card rail parked for review (Stripe `py_…`)", "type": "string" }, "dispute_fee_reviewed_at": { "format": "date-time", "title": "When a person settled the fee the card rail had parked for review", "type": "string" }, "dispute_fee_reviewed_by": { "title": "Who settled the parked fee (the principal)", "type": "string" }, "dispute_fee_waived": { "description": "What of the network's fees the platform did not pass to the hotel on a certified case it lost — both fees, received and countered. Never paid to the hotel: the platform declined to recover it", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute dispute fee waived", "type": "object" }, "dispute_fee_waived_at": { "format": "date-time", "title": "When the certified case was lost and its fees waived — the rolling year of the cap is counted on it", "type": "string" }, "dispute_fee_written_off": { "description": "What of the dispute fee was still owed after the last retry and is carried by the platform", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute dispute fee written off", "type": "object" }, "dispute_fee_written_off_at": { "format": "date-time", "title": "When the owed fee was written off", "type": "string" }, "escalated_at": { "format": "date-time", "title": "When the processor reported the inquiry escalated to a chargeback after the house had answered it — the inquiry's submission no longer counts against the chargeback's one", "type": "string" }, "evidence_due_by": { "format": "date-time", "title": "Evidence due by — the issuer's deadline, typically 7 to 21 days. Missing it loses the case by default.", "type": "string" }, "evidence_file_count": { "title": "How many files the submission attached", "type": "integer" }, "evidence_files": { "description": "The files the submission attached, one per evidence type, as the processor's file ids (Stripe `file_…`, uploaded with purpose `dispute_evidence`)", "items": { "properties": { "evidence_type": { "enum": [ "receipt", "service_documentation", "cancellation_policy", "customer_signature", "duplicate_charge_documentation", "customer_communication", "uncategorized_file" ], "type": "string" }, "file_id": { "type": "string" } }, "required": [ "evidence_type", "file_id" ], "type": "object" }, "title": "Payment dispute evidence files", "type": "array" }, "evidence_packet_version": { "title": "Which assembly of the evidence packet was submitted (`dispute_evidence_packet.packet_version`)", "type": "integer" }, "evidence_past_due": { "title": "Whether the last submission reached the processor after the deadline — its delivery to the issuer is then not guaranteed (Stripe's `evidence_details.past_due`)", "type": "boolean" }, "evidence_refusal": { "title": "The processor's words for the last submission it refused — cleared by a submission it took", "type": "string" }, "evidence_refused_at": { "format": "date-time", "title": "When the processor refused the last submission", "type": "string" }, "evidence_sending_at": { "format": "date-time", "title": "Set while an evidence packet's dispute update is on its way to the processor — written before it is sent, cleared when the processor's answer is recorded. Set without `evidence_submitted_at`, the processor may already hold the evidence: submitting again finishes that packet (the same files, the same key) and records its answer", "type": "string" }, "evidence_submitted_at": { "format": "date-time", "title": "Evidence submitted at", "type": "string" }, "funds_reinstated_at": { "format": "date-time", "title": "Funds reinstated at — set only when the case is won, and the one field that says the money actually came back rather than the paperwork merely closing.", "type": "string" }, "funds_withdrawn_at": { "format": "date-time", "title": "Funds withdrawn at", "type": "string" }, "has_evidence": { "title": "Whether the processor holds evidence for the case (Stripe's `evidence_details.has_evidence`: staged or submitted)", "type": "boolean" }, "hotel_reinstated": { "description": "What goes back to the hotel after a late win — the disputed amount the loss pulled back plus the dispute fee passed on to it", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute hotel reinstated", "type": "object" }, "hotel_reinstated_at": { "format": "date-time", "title": "When the transfer giving the hotel its money back was made — for a late win settled by hand, when the operator recorded it", "type": "string" }, "hotel_reinstated_fee": { "description": "Of `hotel_reinstated`, the dispute fee the hotel had been charged", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute hotel reinstated fee", "type": "object" }, "hotel_reinstated_less_platform_fee": { "description": "What was netted out of `hotel_reinstated`: the platform's application fee the processor refunded to the hotel with the loss's reversal (read off the processor's fee refunds, never the ledger). The hotel already had it back, so the late win returns the reversal net of it and the hotel ends where it was before the dispute — the charge less the platform's fee", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute hotel reinstated less platform fee", "type": "object" }, "hotel_reinstatement": { "enum": [ "transferred", "pending_operator", "settled_by_operator" ], "title": "After a late win (the case lost, then won): transferred (the hotel was given back the amount pulled from it and the fee it was charged, in one transfer) or pending_operator (the processor refused the transfer, or the fee's outcome could not be read back: the operator moves the money, and the card rail does not ask again) or settled_by_operator (the operator recorded what they did about it — `hotel_reinstatement_settlement`)", "type": "string" }, "hotel_reinstatement_code": { "title": "The processor's error code for a transfer it refused (Stripe's `error.code`), when the late win is left for the operator", "type": "string" }, "hotel_reinstatement_detail": { "title": "The processor's words for a transfer it refused, when the late win is left for the operator", "type": "string" }, "hotel_reinstatement_note": { "title": "The operator's words on how a late win left for them was settled — required for a write-off", "type": "string" }, "hotel_reinstatement_settled_by": { "title": "Who recorded the settlement of a late win left for the operator (the principal)", "type": "string" }, "hotel_reinstatement_settlement": { "enum": [ "transferred_by_hand", "written_off" ], "title": "When a late win the card rail could not give back was settled by the operator (`hotel_reinstatement = settled_by_operator`): transferred_by_hand (they paid the hotel what the case owed, outside the rail) or written_off (some or none of it went back; the rest is not owed, for the reason in the note)", "type": "string" }, "hotel_reinstatement_written_off": { "description": "Of what a late win left for the operator owed the hotel, what the operator wrote off rather than paid — `hotel_reinstated` is what did go back", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute hotel reinstatement written off", "type": "object" }, "id": { "title": "Dispute record id", "type": "string" }, "inquiry_evidence_submitted_at": { "format": "date-time", "title": "When the house's evidence answered the inquiry, kept when the case escalated and its evidence clock started again", "type": "string" }, "inquiry_submission_count": { "title": "The processor's submission count when the inquiry escalated; the chargeback's own submission is counted above it", "type": "integer" }, "last_observed_at": { "format": "date-time", "title": "When the processor last said this was the case's state. Webhook delivery is not ordered, so this is the watermark a mirror is checked against: an older view of the case is dropped rather than allowed to regress a decided one.", "type": "string" }, "network_reason_code": { "title": "The card network's own reason code for the case (Stripe `payment_method_details.card.network_reason_code`; Visa `10.4` is card-absent fraud, the code Compelling Evidence 3.0 answers)", "type": "string" }, "opened_at": { "format": "date-time", "title": "Opened at", "type": "string" }, "platform_dispute_cost": { "description": "The net of every platform balance transaction for the case — the network's withdrawal of the amount and its fee, a reinstatement on a win, what the card rail recovered from the hotel (the amount's reversal, the fee's reversal or debit), money returned to the hotel after a late win — negated, so a cost is positive and a case fully passed through is zero. Written by `record_platform_dispute_cost` from the case's platform lines. The received fee Stripe never returns is what a won case leaves here.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute platform dispute cost", "type": "object" }, "psp_dispute_reference": { "title": "The processor's own id for the case — Stripe `du_…`, Adyen dispute `pspReference`. The join key for every later event about this dispute, and the only handle that survives into a representment.", "type": "string" }, "reason": { "enum": [ "bank_cannot_process", "check_returned", "credit_not_processed", "customer_initiated", "debit_not_authorized", "duplicate", "fraudulent", "general", "incorrect_account_details", "insufficient_funds", "noncompliant", "product_not_received", "product_unacceptable", "subscription_canceled", "unrecognized" ], "title": "Reason", "type": "string" }, "recovery_reversal_reference": { "title": "The processor's transfer reversal that pulled the lost case's disputed amount back off the hotel's transfer (Stripe `trr_…`, tagged `aerandil_dispute`)", "type": "string" }, "reinstatement_transfer_reference": { "title": "The processor's transfer that gave the hotel its money back (Stripe `tr_…`, tagged `aerandil_late_win`) — or, settled by hand, the operator's own transfer or payout (`tr_…` / `po_…`)", "type": "string" }, "status": { "enum": [ "inquiry_needs_response", "inquiry_under_review", "inquiry_closed", "needs_response", "under_review", "won", "lost", "prevented" ], "title": "Status", "type": "string" }, "submission_count": { "title": "How many times evidence has been submitted", "type": "integer" }, "visa_ce3_required_actions": { "items": { "enum": [ "missing_customer_identifiers", "missing_disputed_transaction_description", "missing_merchandise_or_services", "missing_prior_undisputed_transaction_description", "missing_prior_undisputed_transactions" ], "type": "string" }, "title": "What the processor says the case still lacks to qualify for Visa Compelling Evidence 3.0 (Stripe's `required_actions`, verbatim)", "type": "array" }, "visa_ce3_status": { "enum": [ "requires_action", "qualified", "not_qualified" ], "title": "The processor's Visa Compelling Evidence 3.0 status for the case (Stripe `evidence_details.enhanced_eligibility.visa_compelling_evidence_3.status`): requires_action, qualified (the processor's own prior transactions already qualify — the packet leaves them alone), or not_qualified (after a submission: sent as standard evidence)", "type": "string" }, "waiver_cap_case_floor": { "title": "The cap's floor in cases: under it a case is covered whatever the account's fees and its own, from its first live month", "type": "integer" }, "waiver_cap_cases": { "title": "How many of the account's cases had taken the cap when this one was certified: waived in the rolling year, or certified and still open", "type": "integer" }, "waiver_cap_limit": { "description": "The account's waiver cap when the case was certified: 25% of the platform fees it paid over the rolling year, net of fees refunded. A case is covered while its own two fees fit under it beside what is taken (`waiver_cap_used` + 2 × the fee received ≤ the cap), or while fewer cases than the floor of five (`waiver_cap_case_floor`) have taken it, whatever the fees", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute waiver cap limit", "type": "object" }, "waiver_cap_used": { "description": "What of the account's waiver cap was taken when the case was certified: the fees waived on its cases lost in the rolling year, plus the fees withdrawn so far on its certified cases still open — in the currency of the case's fee", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute waiver cap used", "type": "object" }, "waiver_certified": { "title": "Whether the case was certified for the dispute-fee waiver when its evidence was submitted: if it is lost, neither of the network's fees is passed to the hotel. Decided from facts the kernel holds — the packet went without gaps and on time, the reason is one the packet defends, the card was not keyed by hand, Radar rated the payment normal and the desk did not proceed past an elevated rating, the account's chargebacks are under 0.5% of its charges, and the cap has headroom. Cleared when an inquiry escalates (the chargeback is certified at its own submission)", "type": "boolean" }, "waiver_chargebacks_in_year": { "title": "The account's chargebacks opened in the rolling year the certification counted (this case included; inquiries are not chargebacks)", "type": "integer" }, "waiver_charges_in_year": { "title": "The account's charges in the rolling year the certification counted — the platform fees Stripe collected on them (`platform_earning` lines)", "type": "integer" }, "waiver_decided_at": { "format": "date-time", "title": "When the waiver was decided — the submission the certification was stamped with", "type": "string" }, "waiver_pledged": { "description": "What a certified case holds of the account's waiver cap while it is open: both of the network's fees as priced at certification — twice the fee Stripe took when the case was received, or twice the last received fee seen at the account when the case carried none. Absent on a case not covered", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute waiver pledged", "type": "object" }, "waiver_radar_risk_level": { "title": "Stripe Radar's rating of the disputed payment at authorisation, as the certification read it (`outcome.risk_level`, verbatim: normal, elevated, highest, not_assessed, unknown) — Stripe's own word, read off the disputed intent's latest charge at certification; never the kernel's assessment", "type": "string" }, "waiver_ratio_charge_floor": { "title": "The charges the rolling year must hold before the chargeback ratio is weighed (1,000): under it, as `waiver_charges_in_year` shows, the ratio was not weighed and cannot be the condition missed", "type": "integer" }, "waiver_refusal": { "title": "Why the case is not covered, in words: the first condition it did not meet", "type": "string" }, "waiver_refusal_condition": { "enum": [ "evidence_gaps", "submitted_late", "reason_not_defended", "hand_keyed", "card_unknown", "radar_not_normal", "radar_unknown", "radar_unread", "elevated_rating_overridden", "no_merchant_account", "dispute_ratio", "cap_exhausted" ], "title": "Which condition the case did not meet first (`WAIVER_REFUSALS`)", "type": "string" } }, "required": [ "id", "status", "reason", "amount", "opened_at", "last_observed_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payment_dispute:read" ] } ], "summary": "Read Payment dispute", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.payment_dispute/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA chargeback or pre-dispute inquiry raised against a settled payment. Mirrored from the processor, which mirrors the card network — the kernel never decides a dispute's state, it records one. The money moves at `opened_at` (withdrawn) and again at `closed_at` if the case is won; between those the funds are held by the network and the payment cannot be refunded outside the dispute process.", "operationId": "get_hospitality_payment_dispute_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.payment_dispute" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payment_dispute:read" ] } ], "summary": "Read Payment dispute as of a watermark", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.payment_dispute/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA chargeback or pre-dispute inquiry raised against a settled payment. Mirrored from the processor, which mirrors the card network — the kernel never decides a dispute's state, it records one. The money moves at `opened_at` (withdrawn) and again at `closed_at` if the case is won; between those the funds are held by the network and the payment cannot be refunded outside the dispute process.", "operationId": "list_links_hospitality_payment_dispute", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payment_dispute:read" ] } ], "summary": "List links of Payment dispute", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.dispute_for_payment", "hospitality.link.evidence_packet_for_dispute", "hospitality.link.platform_ledger_line_for_dispute" ] } } ] }, "/v1/object-types/hospitality.payment_dispute/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA chargeback or pre-dispute inquiry raised against a settled payment. Mirrored from the processor, which mirrors the card network — the kernel never decides a dispute's state, it records one. The money moves at `opened_at` (withdrawn) and again at `closed_at` if the case is won; between those the funds are held by the network and the payment cannot be refunded outside the dispute process.", "operationId": "traverse_hospitality_payment_dispute", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.dispute_for_payment", "hospitality.link.evidence_packet_for_dispute", "hospitality.link.platform_ledger_line_for_dispute" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payment_dispute:read" ] } ], "summary": "Traverse from Payment dispute", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.payment_dispute/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA chargeback or pre-dispute inquiry raised against a settled payment. Mirrored from the processor, which mirrors the card network — the kernel never decides a dispute's state, it records one. The money moves at `opened_at` (withdrawn) and again at `closed_at` if the case is won; between those the funds are held by the network and the payment cannot be refunded outside the dispute process.", "operationId": "search_hospitality_payment_dispute", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_dispute_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_dispute_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_dispute_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_dispute_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "inquiry_needs_response", "inquiry_under_review", "inquiry_closed", "needs_response", "under_review", "won", "lost", "prevented" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reason" }, "type": { "const": "eq" }, "value": { "enum": [ "bank_cannot_process", "check_returned", "credit_not_processed", "customer_initiated", "debit_not_authorized", "duplicate", "fraudulent", "general", "incorrect_account_details", "insufficient_funds", "noncompliant", "product_not_received", "product_unacceptable", "subscription_canceled", "unrecognized" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_due_by" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_due_by" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_due_by" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_submitted_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_submitted_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_submitted_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "submission_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "submission_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "submission_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "funds_withdrawn_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "funds_withdrawn_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "funds_withdrawn_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "funds_reinstated_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "funds_reinstated_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "funds_reinstated_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_observed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_observed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_observed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "charge_still_refundable" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_recovery" }, "type": { "const": "eq" }, "value": { "enum": [ "recovered", "owed", "other_currency", "written_off", "needs_review", "returned", "waived" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_recovered" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_owed" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_recovery_detail" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_recovery_detail" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_packet_version" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_packet_version" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_packet_version" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_files" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "evidence_type": { "enum": [ "receipt", "service_documentation", "cancellation_policy", "customer_signature", "duplicate_charge_documentation", "customer_communication", "uncategorized_file" ], "type": "string" }, "file_id": { "type": "string" } }, "required": [ "evidence_type", "file_id" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_file_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_file_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_file_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_refusal" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_refusal" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_refused_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_refused_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_refused_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "has_evidence" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_past_due" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_attempts" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_attempts" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_attempts" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_attempt_open_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_attempt_open_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_attempt_open_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_last_attempt_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_last_attempt_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_last_attempt_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_written_off" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_written_off_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_written_off_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_written_off_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_sending_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_sending_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_sending_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "platform_dispute_cost" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recovery_reversal_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recovery_reversal_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recovery_reversal_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recovery_reversal_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hotel_reinstatement" }, "type": { "const": "eq" }, "value": { "enum": [ "transferred", "pending_operator", "settled_by_operator" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hotel_reinstated" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hotel_reinstated_fee" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hotel_reinstated_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hotel_reinstated_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hotel_reinstated_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reinstatement_transfer_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reinstatement_transfer_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reinstatement_transfer_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reinstatement_transfer_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hotel_reinstatement_code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hotel_reinstatement_code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hotel_reinstatement_code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hotel_reinstatement_code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hotel_reinstatement_detail" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hotel_reinstatement_detail" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hotel_reinstated_less_platform_fee" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "card_brand" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "card_brand" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "card_brand" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "card_brand" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "network_reason_code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "network_reason_code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "network_reason_code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "network_reason_code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "visa_ce3_status" }, "type": { "const": "eq" }, "value": { "enum": [ "requires_action", "qualified", "not_qualified" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "visa_ce3_required_actions" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "missing_customer_identifiers", "missing_disputed_transaction_description", "missing_merchandise_or_services", "missing_prior_undisputed_transaction_description", "missing_prior_undisputed_transactions" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "escalated_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "escalated_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "escalated_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "inquiry_submission_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "inquiry_submission_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "inquiry_submission_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "inquiry_evidence_submitted_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "inquiry_evidence_submitted_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "inquiry_evidence_submitted_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_review_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_review_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_review_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_review_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_reviewed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_reviewed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_reviewed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_reviewed_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_reviewed_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_reviewed_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_reviewed_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_review_note" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_review_note" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hotel_reinstatement_settlement" }, "type": { "const": "eq" }, "value": { "enum": [ "transferred_by_hand", "written_off" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hotel_reinstatement_written_off" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hotel_reinstatement_settled_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hotel_reinstatement_settled_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hotel_reinstatement_settled_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hotel_reinstatement_settled_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hotel_reinstatement_note" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hotel_reinstatement_note" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_certified" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_decided_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_decided_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_decided_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_refusal" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_refusal" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_refusal_condition" }, "type": { "const": "eq" }, "value": { "enum": [ "evidence_gaps", "submitted_late", "reason_not_defended", "hand_keyed", "card_unknown", "radar_not_normal", "radar_unknown", "radar_unread", "elevated_rating_overridden", "no_merchant_account", "dispute_ratio", "cap_exhausted" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_radar_risk_level" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_radar_risk_level" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_radar_risk_level" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_radar_risk_level" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_chargebacks_in_year" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_chargebacks_in_year" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_chargebacks_in_year" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_charges_in_year" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_charges_in_year" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_charges_in_year" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_ratio_charge_floor" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_ratio_charge_floor" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_ratio_charge_floor" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_cap_used" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_cap_limit" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_cap_cases" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_cap_cases" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_cap_cases" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_pledged" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_cap_case_floor" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_cap_case_floor" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waiver_cap_case_floor" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_waived" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_waived_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_waived_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_fee_waived_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "psp_dispute_reference", "status", "reason", "opened_at", "evidence_due_by", "evidence_submitted_at", "submission_count", "funds_withdrawn_at", "funds_reinstated_at", "closed_at", "last_observed_at", "dispute_fee_recovery", "dispute_fee_recovery_detail", "evidence_packet_version", "evidence_file_count", "evidence_refusal", "evidence_refused_at", "dispute_fee_attempts", "dispute_fee_attempt_open_at", "dispute_fee_last_attempt_at", "dispute_fee_written_off_at", "evidence_sending_at", "recovery_reversal_reference", "hotel_reinstatement", "hotel_reinstated_at", "reinstatement_transfer_reference", "hotel_reinstatement_code", "hotel_reinstatement_detail", "card_brand", "network_reason_code", "visa_ce3_status", "escalated_at", "inquiry_submission_count", "inquiry_evidence_submitted_at", "dispute_fee_review_reference", "dispute_fee_reviewed_at", "dispute_fee_reviewed_by", "dispute_fee_review_note", "hotel_reinstatement_settlement", "hotel_reinstatement_settled_by", "hotel_reinstatement_note", "waiver_decided_at", "waiver_refusal", "waiver_refusal_condition", "waiver_radar_risk_level", "waiver_chargebacks_in_year", "waiver_charges_in_year", "waiver_ratio_charge_floor", "waiver_cap_cases", "waiver_cap_case_floor", "dispute_fee_waived_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment_dispute" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "Disputed amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute amount", "type": "object" }, "card_brand": { "title": "The disputed card's brand as the processor reports it on the case (Stripe `payment_method_details.card.brand`) — what the evidence's page limit is read by when the payment names no stored card", "type": "string" }, "charge_still_refundable": { "title": "Whether the disputed payment can still be refunded. False for most open chargebacks: refunding outside the dispute process is blocked, and doing it anyway pays the cardholder twice.", "type": "boolean" }, "closed_at": { "format": "date-time", "title": "Closed at", "type": "string" }, "dispute_fee": { "description": "What the processor charged for the case, net of any fee it returned — Stripe's dispute fee, read off the dispute's balance transactions (the countered fee comes back on a win; the received fee never does). On a hotel's own account it is passed to the hotel at cost when the case is lost — its own transfer reversal beside the disputed amount, and what the transfer cannot carry debited from the hotel's Stripe balance; `dispute_fee_recovered` says what was. On the platform's, it stays the platform's.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute dispute fee", "type": "object" }, "dispute_fee_attempt_open_at": { "format": "date-time", "title": "Set while a retry is open — written before the processor is asked, cleared when its outcome is recorded; an open retry is asked again under the same key", "type": "string" }, "dispute_fee_attempts": { "title": "How many retries of an owed dispute fee the card rail has opened (the debit at the chargeback's close is not counted)", "type": "integer" }, "dispute_fee_last_attempt_at": { "format": "date-time", "title": "When the card rail last retried the owed fee", "type": "string" }, "dispute_fee_owed": { "description": "What of the dispute fee could not be taken yet — present only while some is owed", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute dispute fee owed", "type": "object" }, "dispute_fee_recovered": { "description": "What of the dispute fee the hotel was charged: off its transfer and debited from its Stripe balance", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute dispute fee recovered", "type": "object" }, "dispute_fee_recovery": { "enum": [ "recovered", "owed", "other_currency", "written_off", "needs_review", "returned", "waived" ], "title": "recovered, owed, other_currency (never converted by guesswork), written_off (the platform carries it after the last retry), needs_review (a retry whose outcome could not be read back from the processor: parked for a person, never retried blind), or returned (the case was won after it was lost: the fee is no longer the hotel's, and what it paid goes back with the disputed amount — see `hotel_reinstatement`), or waived (move 12: the case was certified for the dispute-fee waiver when its evidence was submitted, so the platform did not pass the network's fees through — `dispute_fee_waived`; never a payment to the hotel)", "type": "string" }, "dispute_fee_recovery_detail": { "title": "Stripe's words for why the rest was not taken", "type": "string" }, "dispute_fee_review_note": { "title": "What the person who settled the parked fee found", "type": "string" }, "dispute_fee_review_reference": { "title": "The processor's debit a person found when settling a fee the card rail parked for review (Stripe `py_…`)", "type": "string" }, "dispute_fee_reviewed_at": { "format": "date-time", "title": "When a person settled the fee the card rail had parked for review", "type": "string" }, "dispute_fee_reviewed_by": { "title": "Who settled the parked fee (the principal)", "type": "string" }, "dispute_fee_waived": { "description": "What of the network's fees the platform did not pass to the hotel on a certified case it lost — both fees, received and countered. Never paid to the hotel: the platform declined to recover it", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute dispute fee waived", "type": "object" }, "dispute_fee_waived_at": { "format": "date-time", "title": "When the certified case was lost and its fees waived — the rolling year of the cap is counted on it", "type": "string" }, "dispute_fee_written_off": { "description": "What of the dispute fee was still owed after the last retry and is carried by the platform", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute dispute fee written off", "type": "object" }, "dispute_fee_written_off_at": { "format": "date-time", "title": "When the owed fee was written off", "type": "string" }, "escalated_at": { "format": "date-time", "title": "When the processor reported the inquiry escalated to a chargeback after the house had answered it — the inquiry's submission no longer counts against the chargeback's one", "type": "string" }, "evidence_due_by": { "format": "date-time", "title": "Evidence due by — the issuer's deadline, typically 7 to 21 days. Missing it loses the case by default.", "type": "string" }, "evidence_file_count": { "title": "How many files the submission attached", "type": "integer" }, "evidence_files": { "description": "The files the submission attached, one per evidence type, as the processor's file ids (Stripe `file_…`, uploaded with purpose `dispute_evidence`)", "items": { "properties": { "evidence_type": { "enum": [ "receipt", "service_documentation", "cancellation_policy", "customer_signature", "duplicate_charge_documentation", "customer_communication", "uncategorized_file" ], "type": "string" }, "file_id": { "type": "string" } }, "required": [ "evidence_type", "file_id" ], "type": "object" }, "title": "Payment dispute evidence files", "type": "array" }, "evidence_packet_version": { "title": "Which assembly of the evidence packet was submitted (`dispute_evidence_packet.packet_version`)", "type": "integer" }, "evidence_past_due": { "title": "Whether the last submission reached the processor after the deadline — its delivery to the issuer is then not guaranteed (Stripe's `evidence_details.past_due`)", "type": "boolean" }, "evidence_refusal": { "title": "The processor's words for the last submission it refused — cleared by a submission it took", "type": "string" }, "evidence_refused_at": { "format": "date-time", "title": "When the processor refused the last submission", "type": "string" }, "evidence_sending_at": { "format": "date-time", "title": "Set while an evidence packet's dispute update is on its way to the processor — written before it is sent, cleared when the processor's answer is recorded. Set without `evidence_submitted_at`, the processor may already hold the evidence: submitting again finishes that packet (the same files, the same key) and records its answer", "type": "string" }, "evidence_submitted_at": { "format": "date-time", "title": "Evidence submitted at", "type": "string" }, "funds_reinstated_at": { "format": "date-time", "title": "Funds reinstated at — set only when the case is won, and the one field that says the money actually came back rather than the paperwork merely closing.", "type": "string" }, "funds_withdrawn_at": { "format": "date-time", "title": "Funds withdrawn at", "type": "string" }, "has_evidence": { "title": "Whether the processor holds evidence for the case (Stripe's `evidence_details.has_evidence`: staged or submitted)", "type": "boolean" }, "hotel_reinstated": { "description": "What goes back to the hotel after a late win — the disputed amount the loss pulled back plus the dispute fee passed on to it", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute hotel reinstated", "type": "object" }, "hotel_reinstated_at": { "format": "date-time", "title": "When the transfer giving the hotel its money back was made — for a late win settled by hand, when the operator recorded it", "type": "string" }, "hotel_reinstated_fee": { "description": "Of `hotel_reinstated`, the dispute fee the hotel had been charged", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute hotel reinstated fee", "type": "object" }, "hotel_reinstated_less_platform_fee": { "description": "What was netted out of `hotel_reinstated`: the platform's application fee the processor refunded to the hotel with the loss's reversal (read off the processor's fee refunds, never the ledger). The hotel already had it back, so the late win returns the reversal net of it and the hotel ends where it was before the dispute — the charge less the platform's fee", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute hotel reinstated less platform fee", "type": "object" }, "hotel_reinstatement": { "enum": [ "transferred", "pending_operator", "settled_by_operator" ], "title": "After a late win (the case lost, then won): transferred (the hotel was given back the amount pulled from it and the fee it was charged, in one transfer) or pending_operator (the processor refused the transfer, or the fee's outcome could not be read back: the operator moves the money, and the card rail does not ask again) or settled_by_operator (the operator recorded what they did about it — `hotel_reinstatement_settlement`)", "type": "string" }, "hotel_reinstatement_code": { "title": "The processor's error code for a transfer it refused (Stripe's `error.code`), when the late win is left for the operator", "type": "string" }, "hotel_reinstatement_detail": { "title": "The processor's words for a transfer it refused, when the late win is left for the operator", "type": "string" }, "hotel_reinstatement_note": { "title": "The operator's words on how a late win left for them was settled — required for a write-off", "type": "string" }, "hotel_reinstatement_settled_by": { "title": "Who recorded the settlement of a late win left for the operator (the principal)", "type": "string" }, "hotel_reinstatement_settlement": { "enum": [ "transferred_by_hand", "written_off" ], "title": "When a late win the card rail could not give back was settled by the operator (`hotel_reinstatement = settled_by_operator`): transferred_by_hand (they paid the hotel what the case owed, outside the rail) or written_off (some or none of it went back; the rest is not owed, for the reason in the note)", "type": "string" }, "hotel_reinstatement_written_off": { "description": "Of what a late win left for the operator owed the hotel, what the operator wrote off rather than paid — `hotel_reinstated` is what did go back", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute hotel reinstatement written off", "type": "object" }, "id": { "title": "Dispute record id", "type": "string" }, "inquiry_evidence_submitted_at": { "format": "date-time", "title": "When the house's evidence answered the inquiry, kept when the case escalated and its evidence clock started again", "type": "string" }, "inquiry_submission_count": { "title": "The processor's submission count when the inquiry escalated; the chargeback's own submission is counted above it", "type": "integer" }, "last_observed_at": { "format": "date-time", "title": "When the processor last said this was the case's state. Webhook delivery is not ordered, so this is the watermark a mirror is checked against: an older view of the case is dropped rather than allowed to regress a decided one.", "type": "string" }, "network_reason_code": { "title": "The card network's own reason code for the case (Stripe `payment_method_details.card.network_reason_code`; Visa `10.4` is card-absent fraud, the code Compelling Evidence 3.0 answers)", "type": "string" }, "opened_at": { "format": "date-time", "title": "Opened at", "type": "string" }, "platform_dispute_cost": { "description": "The net of every platform balance transaction for the case — the network's withdrawal of the amount and its fee, a reinstatement on a win, what the card rail recovered from the hotel (the amount's reversal, the fee's reversal or debit), money returned to the hotel after a late win — negated, so a cost is positive and a case fully passed through is zero. Written by `record_platform_dispute_cost` from the case's platform lines. The received fee Stripe never returns is what a won case leaves here.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute platform dispute cost", "type": "object" }, "psp_dispute_reference": { "title": "The processor's own id for the case — Stripe `du_…`, Adyen dispute `pspReference`. The join key for every later event about this dispute, and the only handle that survives into a representment.", "type": "string" }, "reason": { "enum": [ "bank_cannot_process", "check_returned", "credit_not_processed", "customer_initiated", "debit_not_authorized", "duplicate", "fraudulent", "general", "incorrect_account_details", "insufficient_funds", "noncompliant", "product_not_received", "product_unacceptable", "subscription_canceled", "unrecognized" ], "title": "Reason", "type": "string" }, "recovery_reversal_reference": { "title": "The processor's transfer reversal that pulled the lost case's disputed amount back off the hotel's transfer (Stripe `trr_…`, tagged `aerandil_dispute`)", "type": "string" }, "reinstatement_transfer_reference": { "title": "The processor's transfer that gave the hotel its money back (Stripe `tr_…`, tagged `aerandil_late_win`) — or, settled by hand, the operator's own transfer or payout (`tr_…` / `po_…`)", "type": "string" }, "status": { "enum": [ "inquiry_needs_response", "inquiry_under_review", "inquiry_closed", "needs_response", "under_review", "won", "lost", "prevented" ], "title": "Status", "type": "string" }, "submission_count": { "title": "How many times evidence has been submitted", "type": "integer" }, "visa_ce3_required_actions": { "items": { "enum": [ "missing_customer_identifiers", "missing_disputed_transaction_description", "missing_merchandise_or_services", "missing_prior_undisputed_transaction_description", "missing_prior_undisputed_transactions" ], "type": "string" }, "title": "What the processor says the case still lacks to qualify for Visa Compelling Evidence 3.0 (Stripe's `required_actions`, verbatim)", "type": "array" }, "visa_ce3_status": { "enum": [ "requires_action", "qualified", "not_qualified" ], "title": "The processor's Visa Compelling Evidence 3.0 status for the case (Stripe `evidence_details.enhanced_eligibility.visa_compelling_evidence_3.status`): requires_action, qualified (the processor's own prior transactions already qualify — the packet leaves them alone), or not_qualified (after a submission: sent as standard evidence)", "type": "string" }, "waiver_cap_case_floor": { "title": "The cap's floor in cases: under it a case is covered whatever the account's fees and its own, from its first live month", "type": "integer" }, "waiver_cap_cases": { "title": "How many of the account's cases had taken the cap when this one was certified: waived in the rolling year, or certified and still open", "type": "integer" }, "waiver_cap_limit": { "description": "The account's waiver cap when the case was certified: 25% of the platform fees it paid over the rolling year, net of fees refunded. A case is covered while its own two fees fit under it beside what is taken (`waiver_cap_used` + 2 × the fee received ≤ the cap), or while fewer cases than the floor of five (`waiver_cap_case_floor`) have taken it, whatever the fees", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute waiver cap limit", "type": "object" }, "waiver_cap_used": { "description": "What of the account's waiver cap was taken when the case was certified: the fees waived on its cases lost in the rolling year, plus the fees withdrawn so far on its certified cases still open — in the currency of the case's fee", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute waiver cap used", "type": "object" }, "waiver_certified": { "title": "Whether the case was certified for the dispute-fee waiver when its evidence was submitted: if it is lost, neither of the network's fees is passed to the hotel. Decided from facts the kernel holds — the packet went without gaps and on time, the reason is one the packet defends, the card was not keyed by hand, Radar rated the payment normal and the desk did not proceed past an elevated rating, the account's chargebacks are under 0.5% of its charges, and the cap has headroom. Cleared when an inquiry escalates (the chargeback is certified at its own submission)", "type": "boolean" }, "waiver_chargebacks_in_year": { "title": "The account's chargebacks opened in the rolling year the certification counted (this case included; inquiries are not chargebacks)", "type": "integer" }, "waiver_charges_in_year": { "title": "The account's charges in the rolling year the certification counted — the platform fees Stripe collected on them (`platform_earning` lines)", "type": "integer" }, "waiver_decided_at": { "format": "date-time", "title": "When the waiver was decided — the submission the certification was stamped with", "type": "string" }, "waiver_pledged": { "description": "What a certified case holds of the account's waiver cap while it is open: both of the network's fees as priced at certification — twice the fee Stripe took when the case was received, or twice the last received fee seen at the account when the case carried none. Absent on a case not covered", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment dispute waiver pledged", "type": "object" }, "waiver_radar_risk_level": { "title": "Stripe Radar's rating of the disputed payment at authorisation, as the certification read it (`outcome.risk_level`, verbatim: normal, elevated, highest, not_assessed, unknown) — Stripe's own word, read off the disputed intent's latest charge at certification; never the kernel's assessment", "type": "string" }, "waiver_ratio_charge_floor": { "title": "The charges the rolling year must hold before the chargeback ratio is weighed (1,000): under it, as `waiver_charges_in_year` shows, the ratio was not weighed and cannot be the condition missed", "type": "integer" }, "waiver_refusal": { "title": "Why the case is not covered, in words: the first condition it did not meet", "type": "string" }, "waiver_refusal_condition": { "enum": [ "evidence_gaps", "submitted_late", "reason_not_defended", "hand_keyed", "card_unknown", "radar_not_normal", "radar_unknown", "radar_unread", "elevated_rating_overridden", "no_merchant_account", "dispute_ratio", "cap_exhausted" ], "title": "Which condition the case did not meet first (`WAIVER_REFUSALS`)", "type": "string" } }, "required": [ "id", "status", "reason", "amount", "opened_at", "last_observed_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payment_dispute:read" ] } ], "summary": "Search Payment dispute", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.payment_request/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe house asking a guest for money against one booking, with a pay link (Mews's payment request): an `amount`, a `reason` (deposit, prepayment, fee, a missing or declined card), a `kind` (`payment` takes the money, `preauthorization` places a hold captured later) and a required `expires_at`. `pending` until the guest pays on the card rail's hosted page (`completed`, with the payment it produced), the house withdraws it (`cancelled`, only from pending) or the night audit finds it past `expires_at` (`expired`). A completed payment lands on the booking's own account through `record_deposit_payment`, so the deposit engine's status ladder moves; a completed preauthorization is the authorise path's pending payment. Money that moves after a request was cancelled or expired is still recorded — the request completes `late` — because a ledger that refuses a settled payment disagrees with the processor.", "operationId": "get_hospitality_payment_request", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment_request" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "What the guest is asked to pay (or to have held)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment request amount", "type": "object" }, "authentication_detail": { "title": "The issuer's or the processor's words for the demand", "type": "string" }, "authentication_due_by": { "format": "date-time", "title": "The house's deadline for the guest to confirm (`set_sca_chase`); past it, the house is told", "type": "string" }, "authentication_for": { "enum": [ "no_show_fee", "post_stay_collection", "hold_replacement", "hold_top_up", "cancellation_fee" ], "title": "What the off-session attempt the issuer wants confirmed was for", "type": "string" }, "authentication_next_chase_at": { "format": "date-time", "title": "When the card rail next looks at the chase — the next reminder, else the deadline; cleared once the deadline has passed", "type": "string" }, "authentication_overdue_at": { "format": "date-time", "title": "When the deadline passed with the guest not done and the house was told", "type": "string" }, "authentication_page_decline": { "title": "The processor's words for the decline on the page — the chase stays pending", "type": "string" }, "authentication_page_declined_at": { "format": "date-time", "title": "When the guest's card was last declined on the page", "type": "string" }, "authentication_page_overpaid_at": { "format": "date-time", "title": "When the chase's page was paid after what it asked for had been taken another way — the page's payment has no ledger home", "type": "string" }, "authentication_page_overpaid_detail": { "title": "Why the page's payment had no home, and whether it was given back or is left for a person", "type": "string" }, "authentication_page_overpaid_reference": { "title": "The processor's intent the overpaid page took", "type": "string" }, "authentication_page_refund_reference": { "title": "The processor's refund that gave the overpaid page's money back", "type": "string" }, "authentication_reminders": { "title": "How many reminders the house sends before the deadline", "type": "integer" }, "authentication_reminders_sent": { "title": "How many reminders have been taken so far", "type": "integer" }, "authentication_resent_at": { "format": "date-time", "title": "When the desk last re-sent the chase's page (one re-send per ten minutes)", "type": "string" }, "authentication_stay_ref": { "format": "uuid", "title": "The departed stay whose late charges the guest is asked to confirm", "type": "string", "x-aerandil-references": "hospitality.stay" }, "cancellation_reason": { "title": "Why the house withdrew it", "type": "string" }, "cancelled_at": { "format": "date-time", "title": "When the house withdrew it", "type": "string" }, "completed_at": { "format": "date-time", "title": "When the processor settled it", "type": "string" }, "completed_late": { "title": "True when the money arrived after the request was cancelled or had expired — recorded, and worth the desk's look", "type": "boolean" }, "expired_at": { "format": "date-time", "title": "When the night audit expired it", "type": "string" }, "expires_at": { "format": "date-time", "title": "When the request lapses; the night audit closing on or after this instant's date expires it while it is still pending", "type": "string" }, "guest_notice_note": { "title": "Why the pay link was not sent to the guest, when it was not", "type": "string" }, "guest_notice_ref": { "format": "uuid", "title": "The outbound message that carries the pay link to the guest", "type": "string", "x-aerandil-references": "hospitality.guest_message" }, "guest_notified_at": { "format": "date-time", "title": "When the pay link was queued for the guest", "type": "string" }, "id": { "title": "Payment request id", "type": "string" }, "kind": { "enum": [ "payment", "preauthorization" ], "title": "`payment` takes the money; `preauthorization` holds it for capture later", "type": "string" }, "note": { "title": "What the guest reads beside the amount (the pay page's line item)", "type": "string" }, "page_fee_ceiling": { "description": "The `application_fee_amount` the card rail set on the hosted page when it minted it, in the request's currency: the account's dearest card class online, because a Payment Link's fee is fixed before any card exists. When the page completes the rail reads the card it was paid with and refunds the difference to that card's own class to the hotel, recording the outcome on the payment (`record_page_fee`). Absent when the page settles to the platform's own account (no fee) or was minted before the ceiling.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment request page fee ceiling", "type": "object" }, "pay_url": { "title": "The card rail's hosted page the guest pays on — absent until the rail has minted it", "type": "string" }, "payment_id": { "format": "uuid", "title": "The payment the completed request produced", "type": "string", "x-aerandil-references": "hospitality.payment" }, "psp_link_reference": { "title": "The processor's handle on the hosted page (a Stripe Payment Link id), so the rail can switch it off when the request ends", "type": "string" }, "reason": { "enum": [ "deposit", "prepayment", "fee", "payment_card_missing", "payment_card_declined", "authentication_required" ], "title": "Why the house is asking", "type": "string" }, "reauthorisation_count": { "title": "How many times the hold has been re-placed", "type": "integer" }, "reauthorisation_refusal": { "title": "Why the hold could not be re-placed (no stored card, a decline) — it lapses at the issuer, and the desk takes a new guarantee", "type": "string" }, "reauthorisation_refused_at": { "format": "date-time", "title": "When the card rail last tried to re-place the hold and could not", "type": "string" }, "reauthorised_at": { "format": "date-time", "title": "When the card rail last re-placed the hold before the issuer lapsed it", "type": "string" }, "refusal_notice_at": { "format": "date-time", "title": "When the guest was queued a message that their card was not accepted", "type": "string" }, "refusal_notice_note": { "title": "Why the guest was not told their card was not accepted, when they were not", "type": "string" }, "refusal_notice_ref": { "format": "uuid", "title": "The outbound message that tells the guest their card was not accepted", "type": "string", "x-aerandil-references": "hospitality.guest_message" }, "refusal_signal_ref": { "format": "uuid", "title": "The network's answer that refused the hold the guest's card placed on the pay page", "type": "string", "x-aerandil-references": "hospitality.fraud_network_signal" }, "requested_at": { "format": "date-time", "title": "When the house asked", "type": "string" }, "reuse_terms": { "title": "The card terms the pay page showed the guest — what they agreed to when the page saved their card for later charges by the house", "type": "string" }, "status": { "enum": [ "pending", "completed", "cancelled", "expired" ], "title": "pending → completed / cancelled / expired", "type": "string" }, "stuck_psp_reference": { "title": "The processor's intent the issuer refused to complete without the cardholder (a Stripe PaymentIntent left `requires_payment_method`); cancelled once the page is paid", "type": "string" } }, "required": [ "id", "amount", "reason", "kind", "status", "expires_at", "requested_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payment_request:read" ] } ], "summary": "Read Payment request", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.payment_request/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe house asking a guest for money against one booking, with a pay link (Mews's payment request): an `amount`, a `reason` (deposit, prepayment, fee, a missing or declined card), a `kind` (`payment` takes the money, `preauthorization` places a hold captured later) and a required `expires_at`. `pending` until the guest pays on the card rail's hosted page (`completed`, with the payment it produced), the house withdraws it (`cancelled`, only from pending) or the night audit finds it past `expires_at` (`expired`). A completed payment lands on the booking's own account through `record_deposit_payment`, so the deposit engine's status ladder moves; a completed preauthorization is the authorise path's pending payment. Money that moves after a request was cancelled or expired is still recorded — the request completes `late` — because a ledger that refuses a settled payment disagrees with the processor.", "operationId": "get_hospitality_payment_request_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.payment_request" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payment_request:read" ] } ], "summary": "Read Payment request as of a watermark", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.payment_request/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe house asking a guest for money against one booking, with a pay link (Mews's payment request): an `amount`, a `reason` (deposit, prepayment, fee, a missing or declined card), a `kind` (`payment` takes the money, `preauthorization` places a hold captured later) and a required `expires_at`. `pending` until the guest pays on the card rail's hosted page (`completed`, with the payment it produced), the house withdraws it (`cancelled`, only from pending) or the night audit finds it past `expires_at` (`expired`). A completed payment lands on the booking's own account through `record_deposit_payment`, so the deposit engine's status ladder moves; a completed preauthorization is the authorise path's pending payment. Money that moves after a request was cancelled or expired is still recorded — the request completes `late` — because a ledger that refuses a settled payment disagrees with the processor.", "operationId": "list_links_hospitality_payment_request", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payment_request:read" ] } ], "summary": "List links of Payment request", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.payment_request_for_reservation" ] } } ] }, "/v1/object-types/hospitality.payment_request/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe house asking a guest for money against one booking, with a pay link (Mews's payment request): an `amount`, a `reason` (deposit, prepayment, fee, a missing or declined card), a `kind` (`payment` takes the money, `preauthorization` places a hold captured later) and a required `expires_at`. `pending` until the guest pays on the card rail's hosted page (`completed`, with the payment it produced), the house withdraws it (`cancelled`, only from pending) or the night audit finds it past `expires_at` (`expired`). A completed payment lands on the booking's own account through `record_deposit_payment`, so the deposit engine's status ladder moves; a completed preauthorization is the authorise path's pending payment. Money that moves after a request was cancelled or expired is still recorded — the request completes `late` — because a ledger that refuses a settled payment disagrees with the processor.", "operationId": "traverse_hospitality_payment_request", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.payment_request_for_reservation" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payment_request:read" ] } ], "summary": "Traverse from Payment request", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.payment_request/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe house asking a guest for money against one booking, with a pay link (Mews's payment request): an `amount`, a `reason` (deposit, prepayment, fee, a missing or declined card), a `kind` (`payment` takes the money, `preauthorization` places a hold captured later) and a required `expires_at`. `pending` until the guest pays on the card rail's hosted page (`completed`, with the payment it produced), the house withdraws it (`cancelled`, only from pending) or the night audit finds it past `expires_at` (`expired`). A completed payment lands on the booking's own account through `record_deposit_payment`, so the deposit engine's status ladder moves; a completed preauthorization is the authorise path's pending payment. Money that moves after a request was cancelled or expired is still recorded — the request completes `late` — because a ledger that refuses a settled payment disagrees with the processor.", "operationId": "search_hospitality_payment_request", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reason" }, "type": { "const": "eq" }, "value": { "enum": [ "deposit", "prepayment", "fee", "payment_card_missing", "payment_card_declined", "authentication_required" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "payment", "preauthorization" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "pending", "completed", "cancelled", "expired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "note" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "note" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "note" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "note" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "pay_url" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "pay_url" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "pay_url" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "pay_url" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_link_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_link_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_link_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_link_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_id" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.payment" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_late" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancelled_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancelled_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancelled_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_reason" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_reason" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expired_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expired_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expired_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "guest_notified_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "guest_notified_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "guest_notified_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "guest_notice_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.guest_message" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "guest_notice_note" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "guest_notice_note" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refusal_signal_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.fraud_network_signal" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refusal_notice_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refusal_notice_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refusal_notice_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refusal_notice_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.guest_message" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refusal_notice_note" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refusal_notice_note" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reauthorised_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reauthorised_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reauthorised_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reauthorisation_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reauthorisation_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reauthorisation_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reauthorisation_refused_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reauthorisation_refused_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reauthorisation_refused_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reauthorisation_refusal" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reauthorisation_refusal" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reuse_terms" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reuse_terms" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_for" }, "type": { "const": "eq" }, "value": { "enum": [ "no_show_fee", "post_stay_collection", "hold_replacement", "hold_top_up", "cancellation_fee" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_stay_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.stay" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "stuck_psp_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "stuck_psp_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "stuck_psp_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "stuck_psp_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_detail" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_detail" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_due_by" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_due_by" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_due_by" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_reminders" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_reminders" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_reminders" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_reminders_sent" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_reminders_sent" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_reminders_sent" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_next_chase_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_next_chase_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_next_chase_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_overdue_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_overdue_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_overdue_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_page_declined_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_page_declined_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_page_declined_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_page_decline" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_page_decline" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_resent_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_resent_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_resent_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_page_overpaid_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_page_overpaid_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_page_overpaid_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_page_overpaid_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_page_overpaid_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_page_overpaid_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_page_overpaid_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_page_refund_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_page_refund_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_page_refund_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_page_refund_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_page_overpaid_detail" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "authentication_page_overpaid_detail" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "page_fee_ceiling" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "reason", "kind", "status", "expires_at", "requested_at", "note", "pay_url", "psp_link_reference", "completed_at", "cancelled_at", "cancellation_reason", "expired_at", "guest_notified_at", "guest_notice_note", "refusal_notice_at", "refusal_notice_note", "reauthorised_at", "reauthorisation_count", "reauthorisation_refused_at", "reauthorisation_refusal", "reuse_terms", "authentication_for", "stuck_psp_reference", "authentication_detail", "authentication_due_by", "authentication_reminders", "authentication_reminders_sent", "authentication_next_chase_at", "authentication_overdue_at", "authentication_page_declined_at", "authentication_page_decline", "authentication_resent_at", "authentication_page_overpaid_at", "authentication_page_overpaid_reference", "authentication_page_refund_reference", "authentication_page_overpaid_detail" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payment_request" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "What the guest is asked to pay (or to have held)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment request amount", "type": "object" }, "authentication_detail": { "title": "The issuer's or the processor's words for the demand", "type": "string" }, "authentication_due_by": { "format": "date-time", "title": "The house's deadline for the guest to confirm (`set_sca_chase`); past it, the house is told", "type": "string" }, "authentication_for": { "enum": [ "no_show_fee", "post_stay_collection", "hold_replacement", "hold_top_up", "cancellation_fee" ], "title": "What the off-session attempt the issuer wants confirmed was for", "type": "string" }, "authentication_next_chase_at": { "format": "date-time", "title": "When the card rail next looks at the chase — the next reminder, else the deadline; cleared once the deadline has passed", "type": "string" }, "authentication_overdue_at": { "format": "date-time", "title": "When the deadline passed with the guest not done and the house was told", "type": "string" }, "authentication_page_decline": { "title": "The processor's words for the decline on the page — the chase stays pending", "type": "string" }, "authentication_page_declined_at": { "format": "date-time", "title": "When the guest's card was last declined on the page", "type": "string" }, "authentication_page_overpaid_at": { "format": "date-time", "title": "When the chase's page was paid after what it asked for had been taken another way — the page's payment has no ledger home", "type": "string" }, "authentication_page_overpaid_detail": { "title": "Why the page's payment had no home, and whether it was given back or is left for a person", "type": "string" }, "authentication_page_overpaid_reference": { "title": "The processor's intent the overpaid page took", "type": "string" }, "authentication_page_refund_reference": { "title": "The processor's refund that gave the overpaid page's money back", "type": "string" }, "authentication_reminders": { "title": "How many reminders the house sends before the deadline", "type": "integer" }, "authentication_reminders_sent": { "title": "How many reminders have been taken so far", "type": "integer" }, "authentication_resent_at": { "format": "date-time", "title": "When the desk last re-sent the chase's page (one re-send per ten minutes)", "type": "string" }, "authentication_stay_ref": { "format": "uuid", "title": "The departed stay whose late charges the guest is asked to confirm", "type": "string", "x-aerandil-references": "hospitality.stay" }, "cancellation_reason": { "title": "Why the house withdrew it", "type": "string" }, "cancelled_at": { "format": "date-time", "title": "When the house withdrew it", "type": "string" }, "completed_at": { "format": "date-time", "title": "When the processor settled it", "type": "string" }, "completed_late": { "title": "True when the money arrived after the request was cancelled or had expired — recorded, and worth the desk's look", "type": "boolean" }, "expired_at": { "format": "date-time", "title": "When the night audit expired it", "type": "string" }, "expires_at": { "format": "date-time", "title": "When the request lapses; the night audit closing on or after this instant's date expires it while it is still pending", "type": "string" }, "guest_notice_note": { "title": "Why the pay link was not sent to the guest, when it was not", "type": "string" }, "guest_notice_ref": { "format": "uuid", "title": "The outbound message that carries the pay link to the guest", "type": "string", "x-aerandil-references": "hospitality.guest_message" }, "guest_notified_at": { "format": "date-time", "title": "When the pay link was queued for the guest", "type": "string" }, "id": { "title": "Payment request id", "type": "string" }, "kind": { "enum": [ "payment", "preauthorization" ], "title": "`payment` takes the money; `preauthorization` holds it for capture later", "type": "string" }, "note": { "title": "What the guest reads beside the amount (the pay page's line item)", "type": "string" }, "page_fee_ceiling": { "description": "The `application_fee_amount` the card rail set on the hosted page when it minted it, in the request's currency: the account's dearest card class online, because a Payment Link's fee is fixed before any card exists. When the page completes the rail reads the card it was paid with and refunds the difference to that card's own class to the hotel, recording the outcome on the payment (`record_page_fee`). Absent when the page settles to the platform's own account (no fee) or was minted before the ceiling.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payment request page fee ceiling", "type": "object" }, "pay_url": { "title": "The card rail's hosted page the guest pays on — absent until the rail has minted it", "type": "string" }, "payment_id": { "format": "uuid", "title": "The payment the completed request produced", "type": "string", "x-aerandil-references": "hospitality.payment" }, "psp_link_reference": { "title": "The processor's handle on the hosted page (a Stripe Payment Link id), so the rail can switch it off when the request ends", "type": "string" }, "reason": { "enum": [ "deposit", "prepayment", "fee", "payment_card_missing", "payment_card_declined", "authentication_required" ], "title": "Why the house is asking", "type": "string" }, "reauthorisation_count": { "title": "How many times the hold has been re-placed", "type": "integer" }, "reauthorisation_refusal": { "title": "Why the hold could not be re-placed (no stored card, a decline) — it lapses at the issuer, and the desk takes a new guarantee", "type": "string" }, "reauthorisation_refused_at": { "format": "date-time", "title": "When the card rail last tried to re-place the hold and could not", "type": "string" }, "reauthorised_at": { "format": "date-time", "title": "When the card rail last re-placed the hold before the issuer lapsed it", "type": "string" }, "refusal_notice_at": { "format": "date-time", "title": "When the guest was queued a message that their card was not accepted", "type": "string" }, "refusal_notice_note": { "title": "Why the guest was not told their card was not accepted, when they were not", "type": "string" }, "refusal_notice_ref": { "format": "uuid", "title": "The outbound message that tells the guest their card was not accepted", "type": "string", "x-aerandil-references": "hospitality.guest_message" }, "refusal_signal_ref": { "format": "uuid", "title": "The network's answer that refused the hold the guest's card placed on the pay page", "type": "string", "x-aerandil-references": "hospitality.fraud_network_signal" }, "requested_at": { "format": "date-time", "title": "When the house asked", "type": "string" }, "reuse_terms": { "title": "The card terms the pay page showed the guest — what they agreed to when the page saved their card for later charges by the house", "type": "string" }, "status": { "enum": [ "pending", "completed", "cancelled", "expired" ], "title": "pending → completed / cancelled / expired", "type": "string" }, "stuck_psp_reference": { "title": "The processor's intent the issuer refused to complete without the cardholder (a Stripe PaymentIntent left `requires_payment_method`); cancelled once the page is paid", "type": "string" } }, "required": [ "id", "amount", "reason", "kind", "status", "expires_at", "requested_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payment_request:read" ] } ], "summary": "Search Payment request", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.payout/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA payout from a hotel's processor balance to its bank (Stripe's `po_…`), mirrored from the processor's events on the property's merchant account. `status` is the processor's own and `paid` is provisional — a payout can fail after it reads as paid. Once the processor has itemised it, its balance transactions are recorded as `payout_line`s, each matched to the ledger payment it came from, and the payout carries the counts: lines, matched, the net of what did not match, and the fees taken.", "operationId": "get_hospitality_payout", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payout" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "What the payout sends to the bank, as the processor states it (net of everything the lines carried)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payout amount", "type": "object" }, "arrival_date": { "format": "date", "title": "The day the processor expects the money in the bank", "type": "string" }, "automatic": { "title": "Whether the processor paid it out on its schedule. A manual payout cannot be itemised", "type": "boolean" }, "currency": { "title": "The payout's currency (ISO 4217, upper case)", "type": "string" }, "failed_at": { "format": "date-time", "title": "When the ledger heard the payout failed", "type": "string" }, "failure_code": { "title": "The processor's reason the payout failed (`account_closed`, `no_account`, …)", "type": "string" }, "failure_message": { "title": "The processor's words for the failure", "type": "string" }, "fees_total": { "description": "The processor's fees the lines carried: their `fee` fields plus any separate fee lines", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payout fees total", "type": "object" }, "id": { "title": "Payout id", "type": "string" }, "initiated_at": { "format": "date-time", "title": "When the processor created the payout", "type": "string" }, "line_count": { "title": "Balance transactions recorded against the payout", "type": "integer" }, "matched_count": { "title": "Of those, the lines matched to a ledger payment", "type": "integer" }, "merchant_account_id": { "title": "The merchant account whose balance paid out (its object id) — the payout_for_merchant_account edge's target", "type": "string" }, "money_line_count": { "title": "Of the lines, those that are a guest's money and should match a payment (every category bar `fee`, `payout` and `payout_reversal`)", "type": "integer" }, "property_id": { "title": "The house the merchant account settles for (its object id)", "type": "string" }, "psp_reference": { "title": "The processor's id for the payout (Stripe `po_…`) — the replay key every event about it lands on. An identifier, not a credential.", "type": "string" }, "reconciled_at": { "format": "date-time", "title": "When the ledger finished recording the lines", "type": "string" }, "reconciliation_difference": { "description": "The payout's amount less the net of every line bar the payout's own — zero when the lines add up to what the bank was sent; otherwise the payout is `completed_with_difference`", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payout reconciliation difference", "type": "object" }, "reconciliation_status": { "enum": [ "not_started", "in_progress", "completed", "not_applicable", "completed_with_difference" ], "title": "Whether the payout's lines are on the ledger: `in_progress` while the processor itemises it, `not_started` once it has and the ledger has not, `completed` once recorded and adding up to the payout, `completed_with_difference` once recorded but not adding up (`reconciliation_difference`), `not_applicable` for a manual payout", "type": "string" }, "reversed_total": { "description": "The net of the `payout_reversal` lines: an earlier failed payout's money, returned to the balance and sent again in this one", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payout reversed total", "type": "object" }, "status": { "enum": [ "pending", "in_transit", "paid", "failed", "canceled" ], "title": "The processor's payout status; `paid` is provisional", "type": "string" }, "unmatched_amount": { "description": "The size of the money lines (charges, refunds, disputes, transfers) that matched no ledger payment — the sum of their nets' magnitudes, so £50 in and £50 out unmatched is £100, not nothing; computed from the lines, never typed", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payout unmatched amount", "type": "object" }, "unmatched_count": { "title": "Of the money lines, those that matched no ledger payment", "type": "integer" } }, "required": [ "id", "psp_reference", "merchant_account_id", "property_id", "status", "reconciliation_status", "amount", "currency", "initiated_at", "automatic", "line_count", "matched_count" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payout:read" ] } ], "summary": "Read Payout", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.payout/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA payout from a hotel's processor balance to its bank (Stripe's `po_…`), mirrored from the processor's events on the property's merchant account. `status` is the processor's own and `paid` is provisional — a payout can fail after it reads as paid. Once the processor has itemised it, its balance transactions are recorded as `payout_line`s, each matched to the ledger payment it came from, and the payout carries the counts: lines, matched, the net of what did not match, and the fees taken.", "operationId": "get_hospitality_payout_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.payout" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payout:read" ] } ], "summary": "Read Payout as of a watermark", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.payout/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA payout from a hotel's processor balance to its bank (Stripe's `po_…`), mirrored from the processor's events on the property's merchant account. `status` is the processor's own and `paid` is provisional — a payout can fail after it reads as paid. Once the processor has itemised it, its balance transactions are recorded as `payout_line`s, each matched to the ledger payment it came from, and the payout carries the counts: lines, matched, the net of what did not match, and the fees taken.", "operationId": "list_links_hospitality_payout", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payout:read" ] } ], "summary": "List links of Payout", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.payout_for_merchant_account", "hospitality.link.payout_line_for_payout" ] } } ] }, "/v1/object-types/hospitality.payout/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA payout from a hotel's processor balance to its bank (Stripe's `po_…`), mirrored from the processor's events on the property's merchant account. `status` is the processor's own and `paid` is provisional — a payout can fail after it reads as paid. Once the processor has itemised it, its balance transactions are recorded as `payout_line`s, each matched to the ledger payment it came from, and the payout carries the counts: lines, matched, the net of what did not match, and the fees taken.", "operationId": "traverse_hospitality_payout", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.payout_for_merchant_account", "hospitality.link.payout_line_for_payout" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payout:read" ] } ], "summary": "Traverse from Payout", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.payout/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA payout from a hotel's processor balance to its bank (Stripe's `po_…`), mirrored from the processor's events on the property's merchant account. `status` is the processor's own and `paid` is provisional — a payout can fail after it reads as paid. Once the processor has itemised it, its balance transactions are recorded as `payout_line`s, each matched to the ledger payment it came from, and the payout carries the counts: lines, matched, the net of what did not match, and the fees taken.", "operationId": "search_hospitality_payout", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "merchant_account_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "merchant_account_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "merchant_account_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "merchant_account_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "property_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "property_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "property_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "property_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "pending", "in_transit", "paid", "failed", "canceled" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reconciliation_status" }, "type": { "const": "eq" }, "value": { "enum": [ "not_started", "in_progress", "completed", "not_applicable", "completed_with_difference" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "currency" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "currency" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "currency" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "currency" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "arrival_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "arrival_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "arrival_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "initiated_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "initiated_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "initiated_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "automatic" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "failure_code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "failure_code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "failure_code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "failure_code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "failure_message" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "failure_message" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "failure_message" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "failure_message" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "failed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "failed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "failed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "line_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "line_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "line_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "matched_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "matched_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "matched_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "unmatched_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fees_total" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reconciled_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reconciled_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reconciled_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "money_line_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "money_line_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "money_line_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "unmatched_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "unmatched_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "unmatched_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reconciliation_difference" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reversed_total" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "psp_reference", "merchant_account_id", "property_id", "status", "reconciliation_status", "currency", "arrival_date", "initiated_at", "failure_code", "failure_message", "failed_at", "line_count", "matched_count", "reconciled_at", "money_line_count", "unmatched_count" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payout" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "What the payout sends to the bank, as the processor states it (net of everything the lines carried)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payout amount", "type": "object" }, "arrival_date": { "format": "date", "title": "The day the processor expects the money in the bank", "type": "string" }, "automatic": { "title": "Whether the processor paid it out on its schedule. A manual payout cannot be itemised", "type": "boolean" }, "currency": { "title": "The payout's currency (ISO 4217, upper case)", "type": "string" }, "failed_at": { "format": "date-time", "title": "When the ledger heard the payout failed", "type": "string" }, "failure_code": { "title": "The processor's reason the payout failed (`account_closed`, `no_account`, …)", "type": "string" }, "failure_message": { "title": "The processor's words for the failure", "type": "string" }, "fees_total": { "description": "The processor's fees the lines carried: their `fee` fields plus any separate fee lines", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payout fees total", "type": "object" }, "id": { "title": "Payout id", "type": "string" }, "initiated_at": { "format": "date-time", "title": "When the processor created the payout", "type": "string" }, "line_count": { "title": "Balance transactions recorded against the payout", "type": "integer" }, "matched_count": { "title": "Of those, the lines matched to a ledger payment", "type": "integer" }, "merchant_account_id": { "title": "The merchant account whose balance paid out (its object id) — the payout_for_merchant_account edge's target", "type": "string" }, "money_line_count": { "title": "Of the lines, those that are a guest's money and should match a payment (every category bar `fee`, `payout` and `payout_reversal`)", "type": "integer" }, "property_id": { "title": "The house the merchant account settles for (its object id)", "type": "string" }, "psp_reference": { "title": "The processor's id for the payout (Stripe `po_…`) — the replay key every event about it lands on. An identifier, not a credential.", "type": "string" }, "reconciled_at": { "format": "date-time", "title": "When the ledger finished recording the lines", "type": "string" }, "reconciliation_difference": { "description": "The payout's amount less the net of every line bar the payout's own — zero when the lines add up to what the bank was sent; otherwise the payout is `completed_with_difference`", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payout reconciliation difference", "type": "object" }, "reconciliation_status": { "enum": [ "not_started", "in_progress", "completed", "not_applicable", "completed_with_difference" ], "title": "Whether the payout's lines are on the ledger: `in_progress` while the processor itemises it, `not_started` once it has and the ledger has not, `completed` once recorded and adding up to the payout, `completed_with_difference` once recorded but not adding up (`reconciliation_difference`), `not_applicable` for a manual payout", "type": "string" }, "reversed_total": { "description": "The net of the `payout_reversal` lines: an earlier failed payout's money, returned to the balance and sent again in this one", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payout reversed total", "type": "object" }, "status": { "enum": [ "pending", "in_transit", "paid", "failed", "canceled" ], "title": "The processor's payout status; `paid` is provisional", "type": "string" }, "unmatched_amount": { "description": "The size of the money lines (charges, refunds, disputes, transfers) that matched no ledger payment — the sum of their nets' magnitudes, so £50 in and £50 out unmatched is £100, not nothing; computed from the lines, never typed", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payout unmatched amount", "type": "object" }, "unmatched_count": { "title": "Of the money lines, those that matched no ledger payment", "type": "integer" } }, "required": [ "id", "psp_reference", "merchant_account_id", "property_id", "status", "reconciliation_status", "amount", "currency", "initiated_at", "automatic", "line_count", "matched_count" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payout:read" ] } ], "summary": "Search Payout", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.payout_line/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne balance transaction a payout carried (Stripe's `txn_…`): its reporting category, the processor object it came from, the gross, the fee and the net, as the processor states them. `matched` when the source resolves to a ledger payment — a charge to the payment it captured, a refund to its refund leg or original, a dispute to the payment disputed, a destination charge's `py_…` through its transfer to the platform charge. Append-only; a re-run reconciliation may match a line it could not before.", "operationId": "get_hospitality_payout_line", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payout_line" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "Gross, as the processor states it (negative for money out)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payout line amount", "type": "object" }, "available_on": { "format": "date", "title": "The day the line's money became available to pay out", "type": "string" }, "fee": { "description": "The processor's fee on the line", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payout line fee", "type": "object" }, "id": { "title": "Payout line id", "type": "string" }, "line_type": { "title": "The processor's own transaction type (`payment`, `charge`, `payment_refund`, `stripe_fee`, …)", "type": "string" }, "matched": { "title": "Whether the line resolved to a ledger payment", "type": "boolean" }, "net": { "description": "Gross less fee — what the line added to the payout", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payout line net", "type": "object" }, "payment_id": { "title": "The ledger payment the line came from (its object id) — the payout_line_for_payment edge's target", "type": "string" }, "payout_id": { "title": "The payout that carried the line (its object id) — the payout_line_for_payout edge's target", "type": "string" }, "property_id": { "title": "The house the payout is for (its object id)", "type": "string" }, "psp_reference": { "title": "The processor's id for the balance transaction (Stripe `txn_…`) — the replay key", "type": "string" }, "reporting_category": { "enum": [ "charge", "refund", "dispute", "dispute_reversal", "transfer", "transfer_reversal", "fee", "partial_capture_reversal", "payout", "payout_reversal", "adjustment", "other" ], "title": "The processor's reporting category for the line", "type": "string" }, "source_reference": { "title": "The processor object the money came from (`ch_…`, `py_…`, `re_…`, `du_…`, `tr_…`)", "type": "string" } }, "required": [ "id", "psp_reference", "payout_id", "property_id", "reporting_category", "amount", "fee", "net", "matched" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payout_line:read" ] } ], "summary": "Read Payout line", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.payout_line/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne balance transaction a payout carried (Stripe's `txn_…`): its reporting category, the processor object it came from, the gross, the fee and the net, as the processor states them. `matched` when the source resolves to a ledger payment — a charge to the payment it captured, a refund to its refund leg or original, a dispute to the payment disputed, a destination charge's `py_…` through its transfer to the platform charge. Append-only; a re-run reconciliation may match a line it could not before.", "operationId": "get_hospitality_payout_line_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.payout_line" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payout_line:read" ] } ], "summary": "Read Payout line as of a watermark", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.payout_line/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne balance transaction a payout carried (Stripe's `txn_…`): its reporting category, the processor object it came from, the gross, the fee and the net, as the processor states them. `matched` when the source resolves to a ledger payment — a charge to the payment it captured, a refund to its refund leg or original, a dispute to the payment disputed, a destination charge's `py_…` through its transfer to the platform charge. Append-only; a re-run reconciliation may match a line it could not before.", "operationId": "list_links_hospitality_payout_line", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payout_line:read" ] } ], "summary": "List links of Payout line", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.payout_line_for_payment", "hospitality.link.payout_line_for_payout" ] } } ] }, "/v1/object-types/hospitality.payout_line/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne balance transaction a payout carried (Stripe's `txn_…`): its reporting category, the processor object it came from, the gross, the fee and the net, as the processor states them. `matched` when the source resolves to a ledger payment — a charge to the payment it captured, a refund to its refund leg or original, a dispute to the payment disputed, a destination charge's `py_…` through its transfer to the platform charge. Append-only; a re-run reconciliation may match a line it could not before.", "operationId": "traverse_hospitality_payout_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.payout_line_for_payment", "hospitality.link.payout_line_for_payout" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payout_line:read" ] } ], "summary": "Traverse from Payout line", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.payout_line/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne balance transaction a payout carried (Stripe's `txn_…`): its reporting category, the processor object it came from, the gross, the fee and the net, as the processor states them. `matched` when the source resolves to a ledger payment — a charge to the payment it captured, a refund to its refund leg or original, a dispute to the payment disputed, a destination charge's `py_…` through its transfer to the platform charge. Append-only; a re-run reconciliation may match a line it could not before.", "operationId": "search_hospitality_payout_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payout_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "property_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "property_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "property_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "property_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reporting_category" }, "type": { "const": "eq" }, "value": { "enum": [ "charge", "refund", "dispute", "dispute_reversal", "transfer", "transfer_reversal", "fee", "partial_capture_reversal", "payout", "payout_reversal", "adjustment", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "line_type" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "line_type" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "line_type" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "line_type" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fee" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "net" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "available_on" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "available_on" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "available_on" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "matched" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "psp_reference", "payout_id", "property_id", "reporting_category", "line_type", "source_reference", "available_on", "payment_id" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.payout_line" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "Gross, as the processor states it (negative for money out)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payout line amount", "type": "object" }, "available_on": { "format": "date", "title": "The day the line's money became available to pay out", "type": "string" }, "fee": { "description": "The processor's fee on the line", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payout line fee", "type": "object" }, "id": { "title": "Payout line id", "type": "string" }, "line_type": { "title": "The processor's own transaction type (`payment`, `charge`, `payment_refund`, `stripe_fee`, …)", "type": "string" }, "matched": { "title": "Whether the line resolved to a ledger payment", "type": "boolean" }, "net": { "description": "Gross less fee — what the line added to the payout", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Payout line net", "type": "object" }, "payment_id": { "title": "The ledger payment the line came from (its object id) — the payout_line_for_payment edge's target", "type": "string" }, "payout_id": { "title": "The payout that carried the line (its object id) — the payout_line_for_payout edge's target", "type": "string" }, "property_id": { "title": "The house the payout is for (its object id)", "type": "string" }, "psp_reference": { "title": "The processor's id for the balance transaction (Stripe `txn_…`) — the replay key", "type": "string" }, "reporting_category": { "enum": [ "charge", "refund", "dispute", "dispute_reversal", "transfer", "transfer_reversal", "fee", "partial_capture_reversal", "payout", "payout_reversal", "adjustment", "other" ], "title": "The processor's reporting category for the line", "type": "string" }, "source_reference": { "title": "The processor object the money came from (`ch_…`, `py_…`, `re_…`, `du_…`, `tr_…`)", "type": "string" } }, "required": [ "id", "psp_reference", "payout_id", "property_id", "reporting_category", "amount", "fee", "net", "matched" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.payout_line:read" ] } ], "summary": "Search Payout line", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.person/objects/{id}": { "get": { "description": "Read an existing instance.\n\nAn individual person known to the hospitality system — guest, local, member, or any combination across a stay's lifecycle. Persons are tenant-wide so loyalty, recognition, and history follow them across the portfolio. The 'guest' label is a role carried on `reservation_for_guest` and on a stay; the same person may also be a local (visiting a venue without a reservation), a member (enrolled in a membership-club program), or all three.", "operationId": "get_hospitality_person", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person" }, "properties": { "additionalProperties": false, "properties": { "address": { "description": "The guest's own postal address. Required on any tax invoice above the property's simplified-invoice threshold — reg 14(1)(e) of the UK VAT Regulations 1995 wants \"the name and address of the person to whom the goods or services are supplied\", and §14(4) Nr. 1 UStG the same. Snapshotted onto the document at issue.", "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "title": "Person address", "type": "object" }, "consent": { "description": "Marketing consent", "properties": { "marketing_email_consented_at": { "format": "date-time", "type": "string" }, "marketing_email_withdrawn_at": { "format": "date-time", "type": "string" }, "marketing_sms_consented_at": { "format": "date-time", "type": "string" }, "marketing_sms_withdrawn_at": { "format": "date-time", "type": "string" }, "method": { "enum": [ "web_form", "check_in_kiosk", "front_desk", "email_double_opt_in", "phone", "import", "other" ], "type": "string" }, "profiling_consented_at": { "format": "date-time", "type": "string" }, "profiling_withdrawn_at": { "format": "date-time", "type": "string" } }, "title": "Person consent", "type": "object" }, "date_of_birth": { "format": "date", "title": "Date of birth", "type": "string" }, "dietary_observance": { "items": { "enum": [ "halal", "kosher", "jain", "hindu_vegetarian", "buddhist_vegetarian", "eastern_orthodox_fasting", "other_religious" ], "type": "string" }, "title": "Faith-driven dietary requirement (reveals religious observance)", "type": "array" }, "direct_stays": { "title": "Direct-channel checked-out stays (projection)", "type": "integer" }, "email": { "title": "Email", "type": "string" }, "external_ref": { "title": "Source-system key for connector-minted persons", "type": "string" }, "family_name": { "title": "Family name", "type": "string" }, "given_name": { "title": "Given name", "type": "string" }, "last_stay_date": { "format": "date", "title": "Most recent stay departure (projection)", "type": "string" }, "last_stay_date_computed_at": { "format": "date-time", "title": "Last stay date refresh timestamp", "type": "string" }, "lifetime_value": { "description": "Lifetime value (projection over folio history)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Person lifetime value", "type": "object" }, "lifetime_value_computed_at": { "format": "date-time", "title": "Lifetime value refresh timestamp", "type": "string" }, "loyalty_id": { "title": "Loyalty ID", "type": "string" }, "nationality": { "title": "Nationality (ISO 3166-1 alpha-2)", "type": "string" }, "phone": { "title": "Phone", "type": "string" }, "preferences": { "description": "Preferences", "properties": { "connecting_room_ok": { "type": "boolean" }, "dietary": { "items": { "type": "string" }, "type": "array" }, "frequents_venues": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.venue" }, "type": "array" }, "frequents_venues_computed_at": { "format": "date-time", "type": "string" }, "language": { "type": "string" }, "observed_host_notes": { "type": "string" }, "pillow": { "type": "string" }, "preferred_amenity_brands": { "items": { "type": "string" }, "type": "array" }, "quiet_room": { "type": "boolean" }, "room_floor_preference": { "enum": [ "low", "mid", "high", "any" ], "type": "string" }, "room_temperature_c": { "format": "decimal", "type": "string" }, "seating_preference": { "type": "string" } }, "title": "Person preferences", "type": "object" }, "relationship_context": { "description": "Relationship context (Tier 1.4 / 2 §D.2)", "properties": { "important_dates": { "items": { "properties": { "date_of_year": { "type": "string" }, "notes": { "type": "string" }, "occasion": { "enum": [ "birthday", "anniversary", "wedding", "child_birthday", "first_visit_anniversary", "other" ], "type": "string" }, "year_started": { "type": "integer" } }, "required": [ "occasion", "date_of_year" ], "type": "object" }, "type": "array" }, "language_secondary": { "type": "string" }, "local_status": { "enum": [ "not_local", "observed_local", "known_regular", "named_recognised" ], "type": "string" }, "local_status_computed_at": { "format": "date-time", "type": "string" }, "mobility_considerations": { "type": "string" }, "occupation": { "type": "string" } }, "title": "Person relationship context", "type": "object" }, "resolution_status": { "enum": [ "active", "merged_subordinate" ], "title": "Identity-resolution status (proposal 0027)", "type": "string" }, "tax_identifier": { "description": "A personal tax number where a jurisdiction prints one on a guest's invoice. Rare in the UK; ordinary in parts of southern Europe and Latin America.", "title": "Tax identifier", "type": "string" }, "total_stays": { "title": "Total checked-out stays (projection)", "type": "integer" }, "total_stays_computed_at": { "format": "date-time", "title": "Total stays refresh timestamp", "type": "string" }, "vip_recognition": { "description": "VIP recognition assignment (proposal 0025)", "properties": { "assigned_at": { "format": "date-time", "type": "string" }, "is_published_to_member": { "type": "boolean" }, "tier": { "enum": [ "standard", "silver", "gold", "platinum", "ambassador" ], "type": "string" } }, "required": [ "tier", "is_published_to_member" ], "title": "Person vip recognition", "type": "object" } }, "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.person:read" ] } ], "summary": "Read Person", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.person/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nAn individual person known to the hospitality system — guest, local, member, or any combination across a stay's lifecycle. Persons are tenant-wide so loyalty, recognition, and history follow them across the portfolio. The 'guest' label is a role carried on `reservation_for_guest` and on a stay; the same person may also be a local (visiting a venue without a reservation), a member (enrolled in a membership-club program), or all three.", "operationId": "get_hospitality_person_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.person" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.person:read" ] } ], "summary": "Read Person as of a watermark", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.person/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nAn individual person known to the hospitality system — guest, local, member, or any combination across a stay's lifecycle. Persons are tenant-wide so loyalty, recognition, and history follow them across the portfolio. The 'guest' label is a role carried on `reservation_for_guest` and on a stay; the same person may also be a local (visiting a venue without a reservation), a member (enrolled in a membership-club program), or all three.", "operationId": "list_links_hospitality_person", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.person:read" ] } ], "summary": "List links of Person", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.allergy_alert_for_person", "hospitality.link.appointment_for_person", "hospitality.link.fraud_assessment_for_person", "hospitality.link.function_event_contact", "hospitality.link.guest_conversation_for_person", "hospitality.link.guest_feedback_for_person", "hospitality.link.guest_id_document_for_person", "hospitality.link.invoice_billed_to_person", "hospitality.link.lost_found_item_claimed_by", "hospitality.link.lost_found_item_returned_to", "hospitality.link.membership_for_person", "hospitality.link.payment_card_for_person", "hospitality.link.person_companion_of", "hospitality.link.person_frequents_venue", "hospitality.link.person_merged_into", "hospitality.link.recognition_event_for_person", "hospitality.link.recovery_event_for_person", "hospitality.link.reservation_for_guest", "hospitality.link.stored_object_for_person", "hospitality.link.turnaway_for_guest", "hospitality.link.venue_visit_for_person", "hospitality.link.waitlist_entry_for_guest", "hospitality.link.workflow_run_targets_person" ] } } ] }, "/v1/object-types/hospitality.person/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nAn individual person known to the hospitality system — guest, local, member, or any combination across a stay's lifecycle. Persons are tenant-wide so loyalty, recognition, and history follow them across the portfolio. The 'guest' label is a role carried on `reservation_for_guest` and on a stay; the same person may also be a local (visiting a venue without a reservation), a member (enrolled in a membership-club program), or all three.", "operationId": "traverse_hospitality_person", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.allergy_alert_for_person", "hospitality.link.appointment_for_person", "hospitality.link.fraud_assessment_for_person", "hospitality.link.function_event_contact", "hospitality.link.guest_conversation_for_person", "hospitality.link.guest_feedback_for_person", "hospitality.link.guest_id_document_for_person", "hospitality.link.invoice_billed_to_person", "hospitality.link.lost_found_item_claimed_by", "hospitality.link.lost_found_item_returned_to", "hospitality.link.membership_for_person", "hospitality.link.payment_card_for_person", "hospitality.link.person_companion_of", "hospitality.link.person_frequents_venue", "hospitality.link.person_merged_into", "hospitality.link.recognition_event_for_person", "hospitality.link.recovery_event_for_person", "hospitality.link.reservation_for_guest", "hospitality.link.stored_object_for_person", "hospitality.link.turnaway_for_guest", "hospitality.link.venue_visit_for_person", "hospitality.link.waitlist_entry_for_guest", "hospitality.link.workflow_run_targets_person" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.person:read" ] } ], "summary": "Traverse from Person", "tags": [ "people" ] } }, "/v1/object-types/hospitality.person/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nAn individual person known to the hospitality system — guest, local, member, or any combination across a stay's lifecycle. Persons are tenant-wide so loyalty, recognition, and history follow them across the portfolio. The 'guest' label is a role carried on `reservation_for_guest` and on a stay; the same person may also be a local (visiting a venue without a reservation), a member (enrolled in a membership-club program), or all three.", "operationId": "search_hospitality_person", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "given_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "given_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "given_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "given_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "family_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "family_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "family_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "family_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "email" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "email" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "email" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "email" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "phone" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "phone" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "phone" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "phone" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "nationality" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "nationality" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "nationality" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "nationality" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "date_of_birth" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "date_of_birth" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "date_of_birth" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "address" }, "type": { "const": "eq" }, "value": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_identifier" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_identifier" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_identifier" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_identifier" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "preferences" }, "type": { "const": "eq" }, "value": { "properties": { "connecting_room_ok": { "type": "boolean" }, "dietary": { "items": { "type": "string" }, "type": "array" }, "frequents_venues": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.venue" }, "type": "array" }, "frequents_venues_computed_at": { "format": "date-time", "type": "string" }, "language": { "type": "string" }, "observed_host_notes": { "type": "string" }, "pillow": { "type": "string" }, "preferred_amenity_brands": { "items": { "type": "string" }, "type": "array" }, "quiet_room": { "type": "boolean" }, "room_floor_preference": { "enum": [ "low", "mid", "high", "any" ], "type": "string" }, "room_temperature_c": { "format": "decimal", "type": "string" }, "seating_preference": { "type": "string" } }, "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dietary_observance" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "halal", "kosher", "jain", "hindu_vegetarian", "buddhist_vegetarian", "eastern_orthodox_fasting", "other_religious" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "relationship_context" }, "type": { "const": "eq" }, "value": { "properties": { "important_dates": { "items": { "properties": { "date_of_year": { "type": "string" }, "notes": { "type": "string" }, "occasion": { "enum": [ "birthday", "anniversary", "wedding", "child_birthday", "first_visit_anniversary", "other" ], "type": "string" }, "year_started": { "type": "integer" } }, "required": [ "occasion", "date_of_year" ], "type": "object" }, "type": "array" }, "language_secondary": { "type": "string" }, "local_status": { "enum": [ "not_local", "observed_local", "known_regular", "named_recognised" ], "type": "string" }, "local_status_computed_at": { "format": "date-time", "type": "string" }, "mobility_considerations": { "type": "string" }, "occupation": { "type": "string" } }, "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "lifetime_value" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "lifetime_value_computed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "lifetime_value_computed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "lifetime_value_computed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "direct_stays" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "direct_stays" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "direct_stays" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "total_stays" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "total_stays" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "total_stays" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "total_stays_computed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "total_stays_computed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "total_stays_computed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_stay_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_stay_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_stay_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_stay_date_computed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_stay_date_computed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_stay_date_computed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vip_recognition" }, "type": { "const": "eq" }, "value": { "properties": { "assigned_at": { "format": "date-time", "type": "string" }, "is_published_to_member": { "type": "boolean" }, "tier": { "enum": [ "standard", "silver", "gold", "platinum", "ambassador" ], "type": "string" } }, "required": [ "tier", "is_published_to_member" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "loyalty_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "loyalty_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "loyalty_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "loyalty_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "consent" }, "type": { "const": "eq" }, "value": { "properties": { "marketing_email_consented_at": { "format": "date-time", "type": "string" }, "marketing_email_withdrawn_at": { "format": "date-time", "type": "string" }, "marketing_sms_consented_at": { "format": "date-time", "type": "string" }, "marketing_sms_withdrawn_at": { "format": "date-time", "type": "string" }, "method": { "enum": [ "web_form", "check_in_kiosk", "front_desk", "email_double_opt_in", "phone", "import", "other" ], "type": "string" }, "profiling_consented_at": { "format": "date-time", "type": "string" }, "profiling_withdrawn_at": { "format": "date-time", "type": "string" } }, "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "resolution_status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "merged_subordinate" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "given_name", "family_name", "email", "phone", "nationality", "date_of_birth", "tax_identifier", "lifetime_value_computed_at", "direct_stays", "total_stays", "total_stays_computed_at", "last_stay_date", "last_stay_date_computed_at", "loyalty_id", "resolution_status", "external_ref" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person" }, "properties": { "additionalProperties": false, "properties": { "address": { "description": "The guest's own postal address. Required on any tax invoice above the property's simplified-invoice threshold — reg 14(1)(e) of the UK VAT Regulations 1995 wants \"the name and address of the person to whom the goods or services are supplied\", and §14(4) Nr. 1 UStG the same. Snapshotted onto the document at issue.", "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "title": "Person address", "type": "object" }, "consent": { "description": "Marketing consent", "properties": { "marketing_email_consented_at": { "format": "date-time", "type": "string" }, "marketing_email_withdrawn_at": { "format": "date-time", "type": "string" }, "marketing_sms_consented_at": { "format": "date-time", "type": "string" }, "marketing_sms_withdrawn_at": { "format": "date-time", "type": "string" }, "method": { "enum": [ "web_form", "check_in_kiosk", "front_desk", "email_double_opt_in", "phone", "import", "other" ], "type": "string" }, "profiling_consented_at": { "format": "date-time", "type": "string" }, "profiling_withdrawn_at": { "format": "date-time", "type": "string" } }, "title": "Person consent", "type": "object" }, "date_of_birth": { "format": "date", "title": "Date of birth", "type": "string" }, "dietary_observance": { "items": { "enum": [ "halal", "kosher", "jain", "hindu_vegetarian", "buddhist_vegetarian", "eastern_orthodox_fasting", "other_religious" ], "type": "string" }, "title": "Faith-driven dietary requirement (reveals religious observance)", "type": "array" }, "direct_stays": { "title": "Direct-channel checked-out stays (projection)", "type": "integer" }, "email": { "title": "Email", "type": "string" }, "external_ref": { "title": "Source-system key for connector-minted persons", "type": "string" }, "family_name": { "title": "Family name", "type": "string" }, "given_name": { "title": "Given name", "type": "string" }, "last_stay_date": { "format": "date", "title": "Most recent stay departure (projection)", "type": "string" }, "last_stay_date_computed_at": { "format": "date-time", "title": "Last stay date refresh timestamp", "type": "string" }, "lifetime_value": { "description": "Lifetime value (projection over folio history)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Person lifetime value", "type": "object" }, "lifetime_value_computed_at": { "format": "date-time", "title": "Lifetime value refresh timestamp", "type": "string" }, "loyalty_id": { "title": "Loyalty ID", "type": "string" }, "nationality": { "title": "Nationality (ISO 3166-1 alpha-2)", "type": "string" }, "phone": { "title": "Phone", "type": "string" }, "preferences": { "description": "Preferences", "properties": { "connecting_room_ok": { "type": "boolean" }, "dietary": { "items": { "type": "string" }, "type": "array" }, "frequents_venues": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.venue" }, "type": "array" }, "frequents_venues_computed_at": { "format": "date-time", "type": "string" }, "language": { "type": "string" }, "observed_host_notes": { "type": "string" }, "pillow": { "type": "string" }, "preferred_amenity_brands": { "items": { "type": "string" }, "type": "array" }, "quiet_room": { "type": "boolean" }, "room_floor_preference": { "enum": [ "low", "mid", "high", "any" ], "type": "string" }, "room_temperature_c": { "format": "decimal", "type": "string" }, "seating_preference": { "type": "string" } }, "title": "Person preferences", "type": "object" }, "relationship_context": { "description": "Relationship context (Tier 1.4 / 2 §D.2)", "properties": { "important_dates": { "items": { "properties": { "date_of_year": { "type": "string" }, "notes": { "type": "string" }, "occasion": { "enum": [ "birthday", "anniversary", "wedding", "child_birthday", "first_visit_anniversary", "other" ], "type": "string" }, "year_started": { "type": "integer" } }, "required": [ "occasion", "date_of_year" ], "type": "object" }, "type": "array" }, "language_secondary": { "type": "string" }, "local_status": { "enum": [ "not_local", "observed_local", "known_regular", "named_recognised" ], "type": "string" }, "local_status_computed_at": { "format": "date-time", "type": "string" }, "mobility_considerations": { "type": "string" }, "occupation": { "type": "string" } }, "title": "Person relationship context", "type": "object" }, "resolution_status": { "enum": [ "active", "merged_subordinate" ], "title": "Identity-resolution status (proposal 0027)", "type": "string" }, "tax_identifier": { "description": "A personal tax number where a jurisdiction prints one on a guest's invoice. Rare in the UK; ordinary in parts of southern Europe and Latin America.", "title": "Tax identifier", "type": "string" }, "total_stays": { "title": "Total checked-out stays (projection)", "type": "integer" }, "total_stays_computed_at": { "format": "date-time", "title": "Total stays refresh timestamp", "type": "string" }, "vip_recognition": { "description": "VIP recognition assignment (proposal 0025)", "properties": { "assigned_at": { "format": "date-time", "type": "string" }, "is_published_to_member": { "type": "boolean" }, "tier": { "enum": [ "standard", "silver", "gold", "platinum", "ambassador" ], "type": "string" } }, "required": [ "tier", "is_published_to_member" ], "title": "Person vip recognition", "type": "object" } }, "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.person:read" ] } ], "summary": "Search Person", "tags": [ "people" ] } }, "/v1/object-types/hospitality.person_merge_candidate/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA proposed match between two person rows suspected to be the same human, awaiting a merge decision: who matched, how (deterministic key / probabilistic resolver / manual assertion), how strongly, and on which attributes. Confirming creates the `person_merged_into` link and demotes the subordinate to `resolution_status = merged_subordinate`; rejecting permanently suppresses re-proposal of the pair. Candidates are audit rows — terminal statuses are never deleted.", "operationId": "get_hospitality_person_merge_candidate", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person_merge_candidate" }, "properties": { "additionalProperties": false, "properties": { "id": { "title": "Candidate id", "type": "string" }, "match_method": { "enum": [ "deterministic_email", "deterministic_loyalty_id", "deterministic_phone", "probabilistic_name_dob", "probabilistic_fuzzy", "manual" ], "title": "How the candidate was surfaced", "type": "string" }, "match_score": { "format": "decimal", "title": "Match confidence in [0, 1] (1.0 for deterministic / manual)", "type": "string" }, "matched_attributes": { "items": { "type": "string" }, "title": "Attribute names the match keyed on (names only, never values)", "type": "array" }, "person_a": { "format": "uuid", "title": "First person of the proposed pair", "type": "string", "x-aerandil-references": "hospitality.person" }, "person_b": { "format": "uuid", "title": "Second person of the proposed pair", "type": "string", "x-aerandil-references": "hospitality.person" }, "status": { "enum": [ "pending", "confirmed", "rejected", "expired" ], "title": "Candidate lifecycle status", "type": "string" }, "surfaced_at": { "format": "date-time", "title": "When the candidate was proposed", "type": "string" } }, "required": [ "id", "person_a", "person_b", "match_score", "match_method", "status", "surfaced_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.person_merge_candidate:read" ] } ], "summary": "Read Person merge candidate", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.person_merge_candidate/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA proposed match between two person rows suspected to be the same human, awaiting a merge decision: who matched, how (deterministic key / probabilistic resolver / manual assertion), how strongly, and on which attributes. Confirming creates the `person_merged_into` link and demotes the subordinate to `resolution_status = merged_subordinate`; rejecting permanently suppresses re-proposal of the pair. Candidates are audit rows — terminal statuses are never deleted.", "operationId": "get_hospitality_person_merge_candidate_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.person_merge_candidate" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.person_merge_candidate:read" ] } ], "summary": "Read Person merge candidate as of a watermark", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.person_merge_candidate/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA proposed match between two person rows suspected to be the same human, awaiting a merge decision: who matched, how (deterministic key / probabilistic resolver / manual assertion), how strongly, and on which attributes. Confirming creates the `person_merged_into` link and demotes the subordinate to `resolution_status = merged_subordinate`; rejecting permanently suppresses re-proposal of the pair. Candidates are audit rows — terminal statuses are never deleted.", "operationId": "search_hospitality_person_merge_candidate", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "person_a" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.person" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "person_b" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.person" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "match_score" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "match_score" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "match_score" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "match_method" }, "type": { "const": "eq" }, "value": { "enum": [ "deterministic_email", "deterministic_loyalty_id", "deterministic_phone", "probabilistic_name_dob", "probabilistic_fuzzy", "manual" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "matched_attributes" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "pending", "confirmed", "rejected", "expired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "surfaced_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "surfaced_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "surfaced_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "match_score", "match_method", "status", "surfaced_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.person_merge_candidate" }, "properties": { "additionalProperties": false, "properties": { "id": { "title": "Candidate id", "type": "string" }, "match_method": { "enum": [ "deterministic_email", "deterministic_loyalty_id", "deterministic_phone", "probabilistic_name_dob", "probabilistic_fuzzy", "manual" ], "title": "How the candidate was surfaced", "type": "string" }, "match_score": { "format": "decimal", "title": "Match confidence in [0, 1] (1.0 for deterministic / manual)", "type": "string" }, "matched_attributes": { "items": { "type": "string" }, "title": "Attribute names the match keyed on (names only, never values)", "type": "array" }, "person_a": { "format": "uuid", "title": "First person of the proposed pair", "type": "string", "x-aerandil-references": "hospitality.person" }, "person_b": { "format": "uuid", "title": "Second person of the proposed pair", "type": "string", "x-aerandil-references": "hospitality.person" }, "status": { "enum": [ "pending", "confirmed", "rejected", "expired" ], "title": "Candidate lifecycle status", "type": "string" }, "surfaced_at": { "format": "date-time", "title": "When the candidate was proposed", "type": "string" } }, "required": [ "id", "person_a", "person_b", "match_score", "match_method", "status", "surfaced_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.person_merge_candidate:read" ] } ], "summary": "Search Person merge candidate", "tags": [ "people" ] } }, "/v1/object-types/hospitality.platform_ledger_line/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne balance transaction on the platform's own processor balance (Stripe's `txn_…`) that belongs to a hotel's merchant account: the platform charge a destination payment was made with (and Stripe's processing fee on it), the transfer that carried the hotel's share, the application fee the platform earned, a refund and the reversal that recovered it, a chargeback's withdrawal and what was passed back. Filed at the house the account is for, `matched` when it resolves to a ledger payment or case. Append-only; a line read again may gain a match it could not make before. The platform's lines no hotel owns (its own payouts, Stripe's fees on the platform and the tax on them, a reserve, a charge for an account no merchant account holds) are filed at the tenant scope of the operator's own tenant, with no merchant account, never matched, their day the processor's UTC day.", "operationId": "get_hospitality_platform_ledger_line", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.platform_ledger_line" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "Gross on the platform's balance, as the processor states it (negative for money out — a transfer to the hotel, a chargeback)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Platform ledger line amount", "type": "object" }, "available_on": { "format": "date", "title": "The day the line's money became available on the platform's balance", "type": "string" }, "dispute_id": { "title": "The chargeback the line moved money for (its object id) — the platform_ledger_line_for_dispute edge's target", "type": "string" }, "dispute_leg": { "enum": [ "withdrawal", "reinstatement", "amount_recovered", "fee_recovered", "returned_to_hotel" ], "title": "What the line did for its chargeback: the network's withdrawal or reinstatement, the amount or fee recovered from the hotel, money returned to the hotel after a late win", "type": "string" }, "fee": { "description": "The processor's fee on the line, charged to the platform", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Platform ledger line fee", "type": "object" }, "id": { "title": "Platform ledger line id", "type": "string" }, "line_type": { "title": "The processor's own transaction type (`charge`, `transfer`, `application_fee`, `transfer_refund`, `adjustment`, …)", "type": "string" }, "matched": { "title": "Whether the line resolved to a ledger payment or chargeback", "type": "boolean" }, "merchant_account_id": { "title": "The hotel's merchant account the line was for (its object id) — the platform_ledger_line_for_merchant_account edge's target; absent on the platform's own line, which no hotel owns", "type": "string" }, "net": { "description": "Gross less fee — what the line did to the platform's balance", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Platform ledger line net", "type": "object" }, "occurred_at": { "format": "date-time", "title": "When the processor created the balance transaction", "type": "string" }, "occurred_on": { "format": "date", "title": "The house's calendar day the line counts in — the processor's creation instant in the house's own timezone, the close's rule for a card payment's day; computed when the line is recorded", "type": "string" }, "payment_id": { "title": "The ledger payment the line came from (its object id) — the platform_ledger_line_for_payment edge's target", "type": "string" }, "processor_account_reference": { "title": "On the platform's own line: the connected account (`acct_…`) the processor named for it when no merchant account on the ledger holds that account — what the operator looks up to place it", "type": "string" }, "property_id": { "title": "The house the account is for (its object id); absent on the platform's own line", "type": "string" }, "psp_reference": { "title": "The processor's id for the balance transaction on the platform's balance (Stripe `txn_…`) — the replay key", "type": "string" }, "reporting_category": { "enum": [ "charge", "refund", "partial_capture_reversal", "dispute", "dispute_reversal", "transfer", "transfer_reversal", "platform_earning", "platform_earning_refund", "fee", "connect_reserved_funds", "connect_collection_transfer", "payout", "payout_reversal", "other_adjustment", "other", "tax", "risk_reserved_funds", "refund_failure", "topup", "topup_reversal" ], "title": "The processor's reporting category for the line, verbatim (`platform_earning` is an application fee; `other` when the processor named one this ledger does not know)", "type": "string" }, "source_reference": { "title": "The processor object the money moved for (`ch_…`, `tr_…`, `trr_…`, `fee_…`, `fr_…`, `re_…`, `du_…`, `py_…`)", "type": "string" } }, "required": [ "id", "psp_reference", "reporting_category", "amount", "occurred_at", "occurred_on", "matched" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.platform_ledger_line:read" ] } ], "summary": "Read Platform ledger line", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.platform_ledger_line/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne balance transaction on the platform's own processor balance (Stripe's `txn_…`) that belongs to a hotel's merchant account: the platform charge a destination payment was made with (and Stripe's processing fee on it), the transfer that carried the hotel's share, the application fee the platform earned, a refund and the reversal that recovered it, a chargeback's withdrawal and what was passed back. Filed at the house the account is for, `matched` when it resolves to a ledger payment or case. Append-only; a line read again may gain a match it could not make before. The platform's lines no hotel owns (its own payouts, Stripe's fees on the platform and the tax on them, a reserve, a charge for an account no merchant account holds) are filed at the tenant scope of the operator's own tenant, with no merchant account, never matched, their day the processor's UTC day.", "operationId": "get_hospitality_platform_ledger_line_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.platform_ledger_line" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.platform_ledger_line:read" ] } ], "summary": "Read Platform ledger line as of a watermark", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.platform_ledger_line/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne balance transaction on the platform's own processor balance (Stripe's `txn_…`) that belongs to a hotel's merchant account: the platform charge a destination payment was made with (and Stripe's processing fee on it), the transfer that carried the hotel's share, the application fee the platform earned, a refund and the reversal that recovered it, a chargeback's withdrawal and what was passed back. Filed at the house the account is for, `matched` when it resolves to a ledger payment or case. Append-only; a line read again may gain a match it could not make before. The platform's lines no hotel owns (its own payouts, Stripe's fees on the platform and the tax on them, a reserve, a charge for an account no merchant account holds) are filed at the tenant scope of the operator's own tenant, with no merchant account, never matched, their day the processor's UTC day.", "operationId": "list_links_hospitality_platform_ledger_line", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.platform_ledger_line:read" ] } ], "summary": "List links of Platform ledger line", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.platform_ledger_line_for_dispute", "hospitality.link.platform_ledger_line_for_merchant_account", "hospitality.link.platform_ledger_line_for_payment" ] } } ] }, "/v1/object-types/hospitality.platform_ledger_line/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne balance transaction on the platform's own processor balance (Stripe's `txn_…`) that belongs to a hotel's merchant account: the platform charge a destination payment was made with (and Stripe's processing fee on it), the transfer that carried the hotel's share, the application fee the platform earned, a refund and the reversal that recovered it, a chargeback's withdrawal and what was passed back. Filed at the house the account is for, `matched` when it resolves to a ledger payment or case. Append-only; a line read again may gain a match it could not make before. The platform's lines no hotel owns (its own payouts, Stripe's fees on the platform and the tax on them, a reserve, a charge for an account no merchant account holds) are filed at the tenant scope of the operator's own tenant, with no merchant account, never matched, their day the processor's UTC day.", "operationId": "traverse_hospitality_platform_ledger_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.platform_ledger_line_for_dispute", "hospitality.link.platform_ledger_line_for_merchant_account", "hospitality.link.platform_ledger_line_for_payment" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.platform_ledger_line:read" ] } ], "summary": "Traverse from Platform ledger line", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.platform_ledger_line/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne balance transaction on the platform's own processor balance (Stripe's `txn_…`) that belongs to a hotel's merchant account: the platform charge a destination payment was made with (and Stripe's processing fee on it), the transfer that carried the hotel's share, the application fee the platform earned, a refund and the reversal that recovered it, a chargeback's withdrawal and what was passed back. Filed at the house the account is for, `matched` when it resolves to a ledger payment or case. Append-only; a line read again may gain a match it could not make before. The platform's lines no hotel owns (its own payouts, Stripe's fees on the platform and the tax on them, a reserve, a charge for an account no merchant account holds) are filed at the tenant scope of the operator's own tenant, with no merchant account, never matched, their day the processor's UTC day.", "operationId": "search_hospitality_platform_ledger_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "psp_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "merchant_account_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "merchant_account_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "merchant_account_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "merchant_account_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "property_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "property_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "property_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "property_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reporting_category" }, "type": { "const": "eq" }, "value": { "enum": [ "charge", "refund", "partial_capture_reversal", "dispute", "dispute_reversal", "transfer", "transfer_reversal", "platform_earning", "platform_earning_refund", "fee", "connect_reserved_funds", "connect_collection_transfer", "payout", "payout_reversal", "other_adjustment", "other", "tax", "risk_reserved_funds", "refund_failure", "topup", "topup_reversal" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "line_type" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "line_type" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "line_type" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "line_type" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fee" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "net" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "available_on" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "available_on" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "available_on" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "occurred_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "occurred_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "occurred_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "occurred_on" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "occurred_on" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "occurred_on" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "matched" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dispute_leg" }, "type": { "const": "eq" }, "value": { "enum": [ "withdrawal", "reinstatement", "amount_recovered", "fee_recovered", "returned_to_hotel" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "processor_account_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "processor_account_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "processor_account_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "processor_account_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "psp_reference", "merchant_account_id", "property_id", "reporting_category", "line_type", "source_reference", "available_on", "occurred_at", "occurred_on", "payment_id", "dispute_id", "dispute_leg", "processor_account_reference" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.platform_ledger_line" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "Gross on the platform's balance, as the processor states it (negative for money out — a transfer to the hotel, a chargeback)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Platform ledger line amount", "type": "object" }, "available_on": { "format": "date", "title": "The day the line's money became available on the platform's balance", "type": "string" }, "dispute_id": { "title": "The chargeback the line moved money for (its object id) — the platform_ledger_line_for_dispute edge's target", "type": "string" }, "dispute_leg": { "enum": [ "withdrawal", "reinstatement", "amount_recovered", "fee_recovered", "returned_to_hotel" ], "title": "What the line did for its chargeback: the network's withdrawal or reinstatement, the amount or fee recovered from the hotel, money returned to the hotel after a late win", "type": "string" }, "fee": { "description": "The processor's fee on the line, charged to the platform", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Platform ledger line fee", "type": "object" }, "id": { "title": "Platform ledger line id", "type": "string" }, "line_type": { "title": "The processor's own transaction type (`charge`, `transfer`, `application_fee`, `transfer_refund`, `adjustment`, …)", "type": "string" }, "matched": { "title": "Whether the line resolved to a ledger payment or chargeback", "type": "boolean" }, "merchant_account_id": { "title": "The hotel's merchant account the line was for (its object id) — the platform_ledger_line_for_merchant_account edge's target; absent on the platform's own line, which no hotel owns", "type": "string" }, "net": { "description": "Gross less fee — what the line did to the platform's balance", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Platform ledger line net", "type": "object" }, "occurred_at": { "format": "date-time", "title": "When the processor created the balance transaction", "type": "string" }, "occurred_on": { "format": "date", "title": "The house's calendar day the line counts in — the processor's creation instant in the house's own timezone, the close's rule for a card payment's day; computed when the line is recorded", "type": "string" }, "payment_id": { "title": "The ledger payment the line came from (its object id) — the platform_ledger_line_for_payment edge's target", "type": "string" }, "processor_account_reference": { "title": "On the platform's own line: the connected account (`acct_…`) the processor named for it when no merchant account on the ledger holds that account — what the operator looks up to place it", "type": "string" }, "property_id": { "title": "The house the account is for (its object id); absent on the platform's own line", "type": "string" }, "psp_reference": { "title": "The processor's id for the balance transaction on the platform's balance (Stripe `txn_…`) — the replay key", "type": "string" }, "reporting_category": { "enum": [ "charge", "refund", "partial_capture_reversal", "dispute", "dispute_reversal", "transfer", "transfer_reversal", "platform_earning", "platform_earning_refund", "fee", "connect_reserved_funds", "connect_collection_transfer", "payout", "payout_reversal", "other_adjustment", "other", "tax", "risk_reserved_funds", "refund_failure", "topup", "topup_reversal" ], "title": "The processor's reporting category for the line, verbatim (`platform_earning` is an application fee; `other` when the processor named one this ledger does not know)", "type": "string" }, "source_reference": { "title": "The processor object the money moved for (`ch_…`, `tr_…`, `trr_…`, `fee_…`, `fr_…`, `re_…`, `du_…`, `py_…`)", "type": "string" } }, "required": [ "id", "psp_reference", "reporting_category", "amount", "occurred_at", "occurred_on", "matched" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.platform_ledger_line:read" ] } ], "summary": "Search Platform ledger line", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.portfolio/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA grouping of properties under a brand or tenant — typically a region, operating company, or franchisee. Used by chains for reporting and permission rollups.", "operationId": "get_hospitality_portfolio", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.portfolio" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Portfolio code", "type": "string" }, "description": { "title": "Description", "type": "string" }, "name": { "title": "Portfolio name", "type": "string" }, "region": { "enum": [ "north_america", "latin_america", "europe", "middle_east", "africa", "asia", "pacific", "global" ], "title": "Region", "type": "string" } }, "required": [ "code", "name" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.portfolio:read" ] } ], "summary": "Read Portfolio", "tags": [ "organization" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.portfolio/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA grouping of properties under a brand or tenant — typically a region, operating company, or franchisee. Used by chains for reporting and permission rollups.", "operationId": "get_hospitality_portfolio_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.portfolio" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.portfolio:read" ] } ], "summary": "Read Portfolio as of a watermark", "tags": [ "organization" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.portfolio/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA grouping of properties under a brand or tenant — typically a region, operating company, or franchisee. Used by chains for reporting and permission rollups.", "operationId": "list_links_hospitality_portfolio", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.portfolio:read" ] } ], "summary": "List links of Portfolio", "tags": [ "organization" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.brand_has_portfolio", "hospitality.link.portfolio_has_property" ] } } ] }, "/v1/object-types/hospitality.portfolio/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA grouping of properties under a brand or tenant — typically a region, operating company, or franchisee. Used by chains for reporting and permission rollups.", "operationId": "traverse_hospitality_portfolio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.brand_has_portfolio", "hospitality.link.portfolio_has_property" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.portfolio:read" ] } ], "summary": "Traverse from Portfolio", "tags": [ "organization" ] } }, "/v1/object-types/hospitality.portfolio/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA grouping of properties under a brand or tenant — typically a region, operating company, or franchisee. Used by chains for reporting and permission rollups.", "operationId": "search_hospitality_portfolio", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "region" }, "type": { "const": "eq" }, "value": { "enum": [ "north_america", "latin_america", "europe", "middle_east", "africa", "asia", "pacific", "global" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "description", "region" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.portfolio" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Portfolio code", "type": "string" }, "description": { "title": "Description", "type": "string" }, "name": { "title": "Portfolio name", "type": "string" }, "region": { "enum": [ "north_america", "latin_america", "europe", "middle_east", "africa", "asia", "pacific", "global" ], "title": "Region", "type": "string" } }, "required": [ "code", "name" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.portfolio:read" ] } ], "summary": "Search Portfolio", "tags": [ "organization" ] } }, "/v1/object-types/hospitality.pre_shift_lineup_event/objects/{id}": { "get": { "description": "Read an existing instance.\n\nAn instance of a pre-shift lineup (or its absence). Logged per venue per shift so the operator can validate the cadence and so the absence of expected lineups becomes queryable as a drift signal. The `cancelled` flag distinguishes 'lineup scheduled but didn't happen' from 'no lineup attempted'; absence of rows on a venue with `service_register.lineup_format ≠ none` is the structural drift signal. Per proposal §6, the 60-90-day folklore threshold is not hard-coded — operators query their own drift.", "operationId": "get_hospitality_pre_shift_lineup_event", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.pre_shift_lineup_event" }, "properties": { "additionalProperties": false, "properties": { "attendance_count": { "title": "Attendance count", "type": "integer" }, "attendance_principals": { "items": { "type": "string" }, "title": "Attendees (staff identifiers)", "type": "array" }, "cancelled": { "title": "Lineup cancelled (scheduled but didn't happen)", "type": "boolean" }, "culture_moment_present": { "title": "Culture moment shared", "type": "boolean" }, "culture_moment_text": { "title": "Culture moment text", "type": "string" }, "duration_seconds": { "title": "Duration in seconds", "type": "integer" }, "id": { "title": "Lineup event id", "type": "string" }, "leader": { "title": "Leader (staff identifier)", "type": "string" }, "lineup_format": { "enum": [ "group_meeting_15min", "informal_briefing", "one_on_one_per_shift", "none" ], "title": "Lineup format", "type": "string" }, "operational_briefing_present": { "title": "Operational briefing covered", "type": "boolean" }, "operational_briefing_summary": { "title": "Operational briefing summary", "type": "string" }, "standards_reinforcement_topic": { "title": "Standards reinforcement topic", "type": "string" }, "started_at": { "format": "date-time", "title": "When the lineup started", "type": "string" } }, "required": [ "id", "started_at", "duration_seconds", "attendance_count", "culture_moment_present", "operational_briefing_present", "cancelled", "lineup_format" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.pre_shift_lineup_event:read" ] } ], "summary": "Read Pre-shift lineup event", "tags": [ "service_philosophy" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.pre_shift_lineup_event/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nAn instance of a pre-shift lineup (or its absence). Logged per venue per shift so the operator can validate the cadence and so the absence of expected lineups becomes queryable as a drift signal. The `cancelled` flag distinguishes 'lineup scheduled but didn't happen' from 'no lineup attempted'; absence of rows on a venue with `service_register.lineup_format ≠ none` is the structural drift signal. Per proposal §6, the 60-90-day folklore threshold is not hard-coded — operators query their own drift.", "operationId": "get_hospitality_pre_shift_lineup_event_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.pre_shift_lineup_event" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.pre_shift_lineup_event:read" ] } ], "summary": "Read Pre-shift lineup event as of a watermark", "tags": [ "service_philosophy" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.pre_shift_lineup_event/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nAn instance of a pre-shift lineup (or its absence). Logged per venue per shift so the operator can validate the cadence and so the absence of expected lineups becomes queryable as a drift signal. The `cancelled` flag distinguishes 'lineup scheduled but didn't happen' from 'no lineup attempted'; absence of rows on a venue with `service_register.lineup_format ≠ none` is the structural drift signal. Per proposal §6, the 60-90-day folklore threshold is not hard-coded — operators query their own drift.", "operationId": "list_links_hospitality_pre_shift_lineup_event", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.pre_shift_lineup_event:read" ] } ], "summary": "List links of Pre-shift lineup event", "tags": [ "service_philosophy" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.lineup_at_venue", "hospitality.link.pattern_clusters_pre_shift_lineup_event" ] } } ] }, "/v1/object-types/hospitality.pre_shift_lineup_event/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nAn instance of a pre-shift lineup (or its absence). Logged per venue per shift so the operator can validate the cadence and so the absence of expected lineups becomes queryable as a drift signal. The `cancelled` flag distinguishes 'lineup scheduled but didn't happen' from 'no lineup attempted'; absence of rows on a venue with `service_register.lineup_format ≠ none` is the structural drift signal. Per proposal §6, the 60-90-day folklore threshold is not hard-coded — operators query their own drift.", "operationId": "traverse_hospitality_pre_shift_lineup_event", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.lineup_at_venue", "hospitality.link.pattern_clusters_pre_shift_lineup_event" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.pre_shift_lineup_event:read" ] } ], "summary": "Traverse from Pre-shift lineup event", "tags": [ "service_philosophy" ] } }, "/v1/object-types/hospitality.pre_shift_lineup_event/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nAn instance of a pre-shift lineup (or its absence). Logged per venue per shift so the operator can validate the cadence and so the absence of expected lineups becomes queryable as a drift signal. The `cancelled` flag distinguishes 'lineup scheduled but didn't happen' from 'no lineup attempted'; absence of rows on a venue with `service_register.lineup_format ≠ none` is the structural drift signal. Per proposal §6, the 60-90-day folklore threshold is not hard-coded — operators query their own drift.", "operationId": "search_hospitality_pre_shift_lineup_event", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "duration_seconds" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "duration_seconds" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "duration_seconds" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "leader" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "leader" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "leader" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "leader" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "attendance_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "attendance_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "attendance_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "attendance_principals" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "culture_moment_present" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "culture_moment_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "culture_moment_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "standards_reinforcement_topic" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "standards_reinforcement_topic" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "standards_reinforcement_topic" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "standards_reinforcement_topic" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "operational_briefing_present" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "operational_briefing_summary" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "operational_briefing_summary" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancelled" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "lineup_format" }, "type": { "const": "eq" }, "value": { "enum": [ "group_meeting_15min", "informal_briefing", "one_on_one_per_shift", "none" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "started_at", "duration_seconds", "leader", "attendance_count", "culture_moment_text", "standards_reinforcement_topic", "operational_briefing_summary", "lineup_format" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.pre_shift_lineup_event" }, "properties": { "additionalProperties": false, "properties": { "attendance_count": { "title": "Attendance count", "type": "integer" }, "attendance_principals": { "items": { "type": "string" }, "title": "Attendees (staff identifiers)", "type": "array" }, "cancelled": { "title": "Lineup cancelled (scheduled but didn't happen)", "type": "boolean" }, "culture_moment_present": { "title": "Culture moment shared", "type": "boolean" }, "culture_moment_text": { "title": "Culture moment text", "type": "string" }, "duration_seconds": { "title": "Duration in seconds", "type": "integer" }, "id": { "title": "Lineup event id", "type": "string" }, "leader": { "title": "Leader (staff identifier)", "type": "string" }, "lineup_format": { "enum": [ "group_meeting_15min", "informal_briefing", "one_on_one_per_shift", "none" ], "title": "Lineup format", "type": "string" }, "operational_briefing_present": { "title": "Operational briefing covered", "type": "boolean" }, "operational_briefing_summary": { "title": "Operational briefing summary", "type": "string" }, "standards_reinforcement_topic": { "title": "Standards reinforcement topic", "type": "string" }, "started_at": { "format": "date-time", "title": "When the lineup started", "type": "string" } }, "required": [ "id", "started_at", "duration_seconds", "attendance_count", "culture_moment_present", "operational_briefing_present", "cancelled", "lineup_format" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.pre_shift_lineup_event:read" ] } ], "summary": "Search Pre-shift lineup event", "tags": [ "service_philosophy" ] } }, "/v1/object-types/hospitality.prep_station/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA fulfilment station fired lines route to — grill, saute, bar, expo, pastry. fire_course cuts one kitchen ticket per station per course; a menu item's default station is the menu_item_prepared_at_station link.", "operationId": "get_hospitality_prep_station", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.prep_station" }, "properties": { "additionalProperties": false, "properties": { "active": { "title": "Active", "type": "boolean" }, "id": { "title": "Station id", "type": "string" }, "kind": { "enum": [ "grill", "saute", "fry", "cold", "pastry", "pizza", "sushi", "bar", "expo", "other" ], "title": "Station kind", "type": "string" }, "name": { "title": "Station name", "type": "string" } }, "required": [ "id", "name", "kind", "active" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.prep_station:read" ] } ], "summary": "Read Prep station", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.prep_station/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA fulfilment station fired lines route to — grill, saute, bar, expo, pastry. fire_course cuts one kitchen ticket per station per course; a menu item's default station is the menu_item_prepared_at_station link.", "operationId": "get_hospitality_prep_station_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.prep_station" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.prep_station:read" ] } ], "summary": "Read Prep station as of a watermark", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.prep_station/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA fulfilment station fired lines route to — grill, saute, bar, expo, pastry. fire_course cuts one kitchen ticket per station per course; a menu item's default station is the menu_item_prepared_at_station link.", "operationId": "list_links_hospitality_prep_station", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.prep_station:read" ] } ], "summary": "List links of Prep station", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.menu_item_prepared_at_station", "hospitality.link.prep_station_at_outlet", "hospitality.link.ticket_at_station" ] } } ] }, "/v1/object-types/hospitality.prep_station/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA fulfilment station fired lines route to — grill, saute, bar, expo, pastry. fire_course cuts one kitchen ticket per station per course; a menu item's default station is the menu_item_prepared_at_station link.", "operationId": "traverse_hospitality_prep_station", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.menu_item_prepared_at_station", "hospitality.link.prep_station_at_outlet", "hospitality.link.ticket_at_station" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.prep_station:read" ] } ], "summary": "Traverse from Prep station", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.prep_station/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA fulfilment station fired lines route to — grill, saute, bar, expo, pastry. fire_course cuts one kitchen ticket per station per course; a menu item's default station is the menu_item_prepared_at_station link.", "operationId": "search_hospitality_prep_station", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "grill", "saute", "fry", "cold", "pastry", "pizza", "sushi", "bar", "expo", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "active" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "name", "kind" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.prep_station" }, "properties": { "additionalProperties": false, "properties": { "active": { "title": "Active", "type": "boolean" }, "id": { "title": "Station id", "type": "string" }, "kind": { "enum": [ "grill", "saute", "fry", "cold", "pastry", "pizza", "sushi", "bar", "expo", "other" ], "title": "Station kind", "type": "string" }, "name": { "title": "Station name", "type": "string" } }, "required": [ "id", "name", "kind", "active" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.prep_station:read" ] } ], "summary": "Search Prep station", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.privacy_budget_account/objects/{id}": { "get": { "description": "Read an existing instance.\n\nTracks privacy spend for a participant, program, definition, or composition group. Epsilon / delta totals and the running spent / reserved totals are the durable evidence of DP accounting; replays cannot double-spend (proposal 0021 §4.5 / §9).", "operationId": "get_hospitality_privacy_budget_account", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.privacy_budget_account" }, "properties": { "additionalProperties": false, "properties": { "account_scope": { "enum": [ "tenant_program", "property_program", "definition", "composition_group", "output_recipient" ], "title": "tenant_program / property_program / definition / composition_group / output_recipient", "type": "string" }, "alert_thresholds": { "items": { "format": "decimal", "type": "string" }, "title": "Optional thresholds for operator warnings", "type": "array" }, "composition_group": { "title": "Composition group", "type": "string" }, "composition_strategy": { "enum": [ "basic", "advanced", "rdp", "zcdp", "operator_supplied_reviewed" ], "title": "Basic / advanced / RDP / zCDP / operator_supplied_reviewed", "type": "string" }, "definition_api_name": { "title": "Definition api name", "type": "string" }, "delta_total": { "format": "decimal", "title": "Required when delta applies", "type": "string" }, "epsilon_reserved": { "format": "decimal", "title": "Defaults 0", "type": "string" }, "epsilon_spent": { "format": "decimal", "title": "Defaults 0", "type": "string" }, "epsilon_total": { "format": "decimal", "title": "Required for DP accounts", "type": "string" }, "id": { "title": "Account id", "type": "string" }, "last_spend_at": { "format": "date-time", "title": "Audit convenience", "type": "string" }, "mechanism_family": { "enum": [ "central_dp", "local_dp", "dp_sgd", "dp_clean_room", "none_threshold_only" ], "title": "Central DP / local DP / DP-SGD / DP clean room / threshold-only", "type": "string" }, "period_end": { "format": "date-time", "title": "Required unless lifetime", "type": "string" }, "period_kind": { "enum": [ "run", "day", "month", "quarter", "year", "lifetime" ], "title": "Run / day / month / quarter / year / lifetime", "type": "string" }, "period_start": { "format": "date-time", "title": "Period start", "type": "string" }, "program_api_name": { "title": "Program api name", "type": "string" }, "status": { "enum": [ "active", "reserved", "exhausted", "paused", "closed" ], "title": "Lifecycle status", "type": "string" } }, "required": [ "id", "account_scope", "program_api_name", "status", "period_kind", "period_start", "composition_strategy", "mechanism_family" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.privacy_budget_account:read" ] } ], "summary": "Read Privacy budget account", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.privacy_budget_account/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nTracks privacy spend for a participant, program, definition, or composition group. Epsilon / delta totals and the running spent / reserved totals are the durable evidence of DP accounting; replays cannot double-spend (proposal 0021 §4.5 / §9).", "operationId": "get_hospitality_privacy_budget_account_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.privacy_budget_account" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.privacy_budget_account:read" ] } ], "summary": "Read Privacy budget account as of a watermark", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.privacy_budget_account/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nTracks privacy spend for a participant, program, definition, or composition group. Epsilon / delta totals and the running spent / reserved totals are the durable evidence of DP accounting; replays cannot double-spend (proposal 0021 §4.5 / §9).", "operationId": "list_links_hospitality_privacy_budget_account", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.privacy_budget_account:read" ] } ], "summary": "List links of Privacy budget account", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.federated_run_reserved_from_account", "hospitality.link.privacy_budget_for_participation" ] } } ] }, "/v1/object-types/hospitality.privacy_budget_account/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nTracks privacy spend for a participant, program, definition, or composition group. Epsilon / delta totals and the running spent / reserved totals are the durable evidence of DP accounting; replays cannot double-spend (proposal 0021 §4.5 / §9).", "operationId": "traverse_hospitality_privacy_budget_account", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.federated_run_reserved_from_account", "hospitality.link.privacy_budget_for_participation" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.privacy_budget_account:read" ] } ], "summary": "Traverse from Privacy budget account", "tags": [ "federated_intelligence" ] } }, "/v1/object-types/hospitality.privacy_budget_account/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nTracks privacy spend for a participant, program, definition, or composition group. Epsilon / delta totals and the running spent / reserved totals are the durable evidence of DP accounting; replays cannot double-spend (proposal 0021 §4.5 / §9).", "operationId": "search_hospitality_privacy_budget_account", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "account_scope" }, "type": { "const": "eq" }, "value": { "enum": [ "tenant_program", "property_program", "definition", "composition_group", "output_recipient" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "program_api_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "program_api_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "program_api_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "program_api_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_api_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_api_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_api_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_api_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "composition_group" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "composition_group" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "composition_group" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "composition_group" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "reserved", "exhausted", "paused", "closed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "run", "day", "month", "quarter", "year", "lifetime" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_start" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_start" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_start" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_end" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_end" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_end" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "epsilon_total" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "epsilon_total" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "epsilon_total" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "epsilon_reserved" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "epsilon_reserved" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "epsilon_reserved" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "epsilon_spent" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "epsilon_spent" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "epsilon_spent" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delta_total" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delta_total" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delta_total" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "composition_strategy" }, "type": { "const": "eq" }, "value": { "enum": [ "basic", "advanced", "rdp", "zcdp", "operator_supplied_reviewed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "mechanism_family" }, "type": { "const": "eq" }, "value": { "enum": [ "central_dp", "local_dp", "dp_sgd", "dp_clean_room", "none_threshold_only" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "alert_thresholds" }, "type": { "const": "eq" }, "value": { "items": { "format": "decimal", "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_spend_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_spend_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_spend_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "account_scope", "program_api_name", "definition_api_name", "composition_group", "status", "period_kind", "period_start", "period_end", "epsilon_total", "epsilon_reserved", "epsilon_spent", "delta_total", "composition_strategy", "mechanism_family", "last_spend_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.privacy_budget_account" }, "properties": { "additionalProperties": false, "properties": { "account_scope": { "enum": [ "tenant_program", "property_program", "definition", "composition_group", "output_recipient" ], "title": "tenant_program / property_program / definition / composition_group / output_recipient", "type": "string" }, "alert_thresholds": { "items": { "format": "decimal", "type": "string" }, "title": "Optional thresholds for operator warnings", "type": "array" }, "composition_group": { "title": "Composition group", "type": "string" }, "composition_strategy": { "enum": [ "basic", "advanced", "rdp", "zcdp", "operator_supplied_reviewed" ], "title": "Basic / advanced / RDP / zCDP / operator_supplied_reviewed", "type": "string" }, "definition_api_name": { "title": "Definition api name", "type": "string" }, "delta_total": { "format": "decimal", "title": "Required when delta applies", "type": "string" }, "epsilon_reserved": { "format": "decimal", "title": "Defaults 0", "type": "string" }, "epsilon_spent": { "format": "decimal", "title": "Defaults 0", "type": "string" }, "epsilon_total": { "format": "decimal", "title": "Required for DP accounts", "type": "string" }, "id": { "title": "Account id", "type": "string" }, "last_spend_at": { "format": "date-time", "title": "Audit convenience", "type": "string" }, "mechanism_family": { "enum": [ "central_dp", "local_dp", "dp_sgd", "dp_clean_room", "none_threshold_only" ], "title": "Central DP / local DP / DP-SGD / DP clean room / threshold-only", "type": "string" }, "period_end": { "format": "date-time", "title": "Required unless lifetime", "type": "string" }, "period_kind": { "enum": [ "run", "day", "month", "quarter", "year", "lifetime" ], "title": "Run / day / month / quarter / year / lifetime", "type": "string" }, "period_start": { "format": "date-time", "title": "Period start", "type": "string" }, "program_api_name": { "title": "Program api name", "type": "string" }, "status": { "enum": [ "active", "reserved", "exhausted", "paused", "closed" ], "title": "Lifecycle status", "type": "string" } }, "required": [ "id", "account_scope", "program_api_name", "status", "period_kind", "period_start", "composition_strategy", "mechanism_family" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.privacy_budget_account:read" ] } ], "summary": "Search Privacy budget account", "tags": [ "federated_intelligence" ] } }, "/v1/object-types/hospitality.privacy_budget_event/objects/{id}": { "get": { "description": "Read an existing instance.\n\nImmutable ledger row recording one reservation / commit / release / exhaustion / adjustment against a `privacy_budget_account`. UNIQUE on `(account_id, correlation_id, event_kind)` (migration 0015) so duplicate submissions are no-ops — the Brandur idempotency pattern transposed onto DP accounting.", "operationId": "get_hospitality_privacy_budget_event", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.privacy_budget_event" }, "properties": { "additionalProperties": false, "properties": { "account_id": { "title": "Privacy budget account this event acts on", "type": "string" }, "applied_at": { "format": "date-time", "title": "Wall-clock timestamp of the ledger write", "type": "string" }, "correlation_id": { "title": "Originating run / batch correlation id — keys the commit-once idempotency", "type": "string" }, "delta_delta": { "format": "decimal", "title": "Signed change in δ; populated when the account carries an explicit (ε, δ) shape.", "type": "string" }, "epsilon_delta": { "format": "decimal", "title": "Signed change in ε; required for basic / advanced composition accounts. Positive on reserve / commit (budget consumed); positive on release (budget returned to available). The account projection reads delta and the kind together to know whether to increment epsilon_reserved or epsilon_spent.", "type": "string" }, "event_kind": { "enum": [ "reserve", "commit", "release", "exhaust", "adjust" ], "title": "reserve / commit / release / exhaust / adjust", "type": "string" }, "id": { "title": "Event id", "type": "string" }, "reason": { "title": "Optional free-text reason (audit only; bounded)", "type": "string" }, "rho_delta": { "format": "decimal", "title": "Signed change in ρ for zCDP-accounted accounts. The seam to rho-additive composition (Bun–Steinke 2016); v1 leaves this field unwritten for basic-composition accounts.", "type": "string" } }, "required": [ "id", "account_id", "correlation_id", "event_kind", "applied_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.privacy_budget_event:read" ] } ], "summary": "Read Privacy budget event", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.privacy_budget_event/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nImmutable ledger row recording one reservation / commit / release / exhaustion / adjustment against a `privacy_budget_account`. UNIQUE on `(account_id, correlation_id, event_kind)` (migration 0015) so duplicate submissions are no-ops — the Brandur idempotency pattern transposed onto DP accounting.", "operationId": "get_hospitality_privacy_budget_event_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.privacy_budget_event" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.privacy_budget_event:read" ] } ], "summary": "Read Privacy budget event as of a watermark", "tags": [ "federated_intelligence" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.privacy_budget_event/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nImmutable ledger row recording one reservation / commit / release / exhaustion / adjustment against a `privacy_budget_account`. UNIQUE on `(account_id, correlation_id, event_kind)` (migration 0015) so duplicate submissions are no-ops — the Brandur idempotency pattern transposed onto DP accounting.", "operationId": "search_hospitality_privacy_budget_event", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "account_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "account_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "account_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "account_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "correlation_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "correlation_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "correlation_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "correlation_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "event_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "reserve", "commit", "release", "exhaust", "adjust" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "epsilon_delta" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "epsilon_delta" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "epsilon_delta" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delta_delta" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delta_delta" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delta_delta" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rho_delta" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rho_delta" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rho_delta" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "account_id", "correlation_id", "event_kind", "epsilon_delta", "delta_delta", "rho_delta", "reason", "applied_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.privacy_budget_event" }, "properties": { "additionalProperties": false, "properties": { "account_id": { "title": "Privacy budget account this event acts on", "type": "string" }, "applied_at": { "format": "date-time", "title": "Wall-clock timestamp of the ledger write", "type": "string" }, "correlation_id": { "title": "Originating run / batch correlation id — keys the commit-once idempotency", "type": "string" }, "delta_delta": { "format": "decimal", "title": "Signed change in δ; populated when the account carries an explicit (ε, δ) shape.", "type": "string" }, "epsilon_delta": { "format": "decimal", "title": "Signed change in ε; required for basic / advanced composition accounts. Positive on reserve / commit (budget consumed); positive on release (budget returned to available). The account projection reads delta and the kind together to know whether to increment epsilon_reserved or epsilon_spent.", "type": "string" }, "event_kind": { "enum": [ "reserve", "commit", "release", "exhaust", "adjust" ], "title": "reserve / commit / release / exhaust / adjust", "type": "string" }, "id": { "title": "Event id", "type": "string" }, "reason": { "title": "Optional free-text reason (audit only; bounded)", "type": "string" }, "rho_delta": { "format": "decimal", "title": "Signed change in ρ for zCDP-accounted accounts. The seam to rho-additive composition (Bun–Steinke 2016); v1 leaves this field unwritten for basic-composition accounts.", "type": "string" } }, "required": [ "id", "account_id", "correlation_id", "event_kind", "applied_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.privacy_budget_event:read" ] } ], "summary": "Search Privacy budget event", "tags": [ "federated_intelligence" ] } }, "/v1/object-types/hospitality.property/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA single operated site — a hotel or resort, or a non-lodging business run on the same substrate (a standalone day spa). The property is the canonical home of most operational data and the anchor for local timezone, currency, and brand standards.", "operationId": "get_hospitality_property", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" }, "properties": { "additionalProperties": false, "properties": { "address": { "description": "Address", "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "title": "Property address", "type": "object" }, "billing_identity": { "description": "Who this property is, legally, on a document it issues. Absent until an operator fills it in, and `issue_invoice` refuses without it — a tax invoice with no supplier registration number is not one. Snapshotted onto every invoice at issue, so editing this never rewrites a document already handed over.", "properties": { "bank_account": { "properties": { "account_name": { "type": "string" }, "account_number": { "type": "string" }, "bic": { "type": "string" }, "iban": { "type": "string" }, "sort_code": { "type": "string" } }, "type": "object" }, "company_registration_number": { "type": "string" }, "contact_email": { "type": "string" }, "contact_phone": { "type": "string" }, "invoice_address": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "type": "object" }, "invoice_issue_deadline_days": { "type": "integer" }, "invoice_number_prefix": { "type": "string" }, "payment_terms_days": { "type": "integer" }, "simplified_invoice_threshold": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "tax_registration_number": { "type": "string" }, "tax_registration_scheme": { "enum": [ "vat", "gst", "sales_tax", "none" ], "type": "string" } }, "required": [ "tax_registration_scheme" ], "title": "Property billing identity", "type": "object" }, "business_date_opened_at": { "description": "When the open business date was opened. A posting stamped before this instant belongs to an earlier day and is dated by the property-local calendar instead.", "format": "date-time", "title": "Open business date opened at", "type": "string" }, "code": { "title": "Property code", "type": "string" }, "credit_limit_overage": { "enum": [ "off", "hold", "charge" ], "title": "What the night audit does once a stay's bill reaches what its holds are for: off, hold the excess, or charge (set_credit_limit_overage; off unset)", "type": "string" }, "default_currency": { "format": "iso-4217", "title": "Default currency (ISO 4217)", "type": "string" }, "description": { "title": "Description", "type": "string" }, "fnb_open_checks_at_roll": { "enum": [ "carry", "refuse" ], "title": "What the night audit does with the outlets' checks still open on the day it closes: carry them on their own business date, or refuse the close (set_fnb_open_checks_policy; carry unset)", "type": "string" }, "hold_top_up": { "title": "Whether the night audit tops up an in-house stay's card hold as its bill grows (set_hold_top_up; off unset)", "type": "boolean" }, "hold_top_up_interval_minutes": { "title": "How often, in minutes, the card rail plans the house's in-house stays' top-ups between night audits (60 to 1440; 0 or unset: at the audit and on the desk's press only)", "type": "integer" }, "hold_top_up_max_per_stay": { "title": "The most top-ups the card rail places for one stay", "type": "integer" }, "hold_top_up_threshold": { "description": "The smallest excess worth a top-up — the bill less what is held plus the rule's allowance", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Property hold top up threshold", "type": "object" }, "kind": { "enum": [ "hotel", "resort", "residences", "serviced_apartments", "hostel", "glamping", "mixed_use", "day_spa", "restaurant" ], "title": "Property kind", "type": "string" }, "legal_name": { "title": "Legal name", "type": "string" }, "location": { "properties": { "lat": { "type": "number" }, "lon": { "type": "number" } }, "required": [ "lat", "lon" ], "title": "Geo location", "type": "object" }, "name": { "title": "Property name", "type": "string" }, "open_business_date": { "description": "The business date this property has open — the hotel date a posting made now is dated to. Written by open_business_date and the night audit's close; unset while no day is open.", "format": "date", "title": "Open business date", "type": "string" }, "opened_on": { "format": "date", "title": "Opened on", "type": "string" }, "payment_request_messaging": { "description": "When true, a payment request's pay link is sent to the booking's guest — by email, or by SMS when the profile holds no email — as soon as the card rail has minted it. Unset: off, and the desk sends the link itself.", "title": "Send pay links to the guest", "type": "boolean" }, "payment_request_reuse_terms": { "description": "What the pay page tells the guest about keeping their card (Stripe's submit-button text, at most 1,200 characters): that the house may charge it without them present, for what, when and how often, and how each amount is set — the terms Stripe requires for a merchant-initiated charge. Set with `set_payment_request_messaging`. Unset: the card rail's default wording.", "title": "Pay page card terms", "type": "string" }, "positioning": { "enum": [ "luxury", "upper_upscale", "upscale", "upper_midscale", "midscale", "economy", "boutique", "lifestyle" ], "title": "Market positioning", "type": "string" }, "post_stay_charging_days": { "description": "How many business days after departure a charge found later (the minibar, damage, laundry) may still be posted to the departed stay's bill and taken from its card. On (1–14), check-out keeps the stay's largest card hold and releases the rest, and the window closes at the house's midnight after its last day — 1 is OPERA's \"until the end of the business date\". Off (0 or unset), check-out releases every hold. Set with `set_post_stay_charging`.", "title": "Post-stay charging window, in days (0 = off)", "type": "integer" }, "request_soon_minutes": { "description": "How many minutes before its due time a housekeeping request reads as `soon` on the housekeeping_requests read (and on the handset's card). Unset: 30. Between 1 and 720. Set through set_request_urgency_window.", "title": "Minutes ahead within which a request reads as soon", "type": "integer" }, "room_count": { "title": "Total rooms", "type": "integer" }, "sca_chase": { "description": "When true, a charge or hold the card rail tried with the guest absent that the issuer will only complete with the cardholder sends the guest a page to confirm it on (email first, else SMS, under the service-message consent gate), reminds them before the deadline, and tells the house when the deadline passes. Unset: off — the state and its deadline are still recorded and the desk sends the page itself. Set with `set_sca_chase`.", "title": "Chase a guest whose bank asks them to confirm", "type": "boolean" }, "sca_chase_hours": { "description": "The house's deadline for a pending authentication, in hours from the moment the issuer asked (1–168). Unset: 24.", "title": "Hours the guest has to confirm", "type": "integer" }, "sca_chase_reminders": { "description": "How many reminders go to the guest before the deadline, spread evenly across it (0–3; 1 is one at half-time). Unset: 1.", "title": "Reminders before the deadline", "type": "integer" }, "standard_week_hours": { "format": "decimal", "title": "Standard work week hours", "type": "string" }, "star_rating": { "format": "decimal", "title": "Star rating", "type": "string" }, "timezone": { "title": "IANA timezone", "type": "string" }, "visitor_key_grace_days": { "description": "How many days past a stay's arrival night the night audit keeps the booking engine's visitor key on its offers, turnaways and reservation before stripping it; the records themselves stay. Unset: 30. At most 365.", "title": "Days past the arrival night a visitor key is kept", "type": "integer" }, "waitlist_claim_url_base": { "description": "The start of the link a waitlist offer carries; the offer's claim token is appended as a path segment. Point it at the kernel's own claim page (`https:///v1/waitlist-claims/`) or at a booking site that calls the claim route. An https URL ending in `/`, with no query or fragment (plain http only to a loopback dev host). Unset: the offer goes out without a link and asks the guest to call.", "title": "Where a waitlist claim link points", "type": "string" }, "waitlist_offer_hold_minutes": { "description": "How many minutes a waitlist offer — the desk's or the matcher's — keeps its room-nights before they are given back and offered to the next entry. Unset: 30. Between 1 and 1440 (OPERA's room-hold range).", "title": "Minutes a waitlist offer keeps its room-nights", "type": "integer" }, "waitlist_offer_messaging": { "description": "When true, every waitlist offer — the desk's or the matcher's — is sent to the guest by SMS (or email when the profile holds no phone), with a link to claim it. Unset: off.", "title": "Send waitlist offers to the guest", "type": "boolean" } }, "required": [ "code", "name", "kind", "timezone", "default_currency" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.property:read" ] } ], "summary": "Read Property", "tags": [ "organization" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.property/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA single operated site — a hotel or resort, or a non-lodging business run on the same substrate (a standalone day spa). The property is the canonical home of most operational data and the anchor for local timezone, currency, and brand standards.", "operationId": "get_hospitality_property_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.property" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.property:read" ] } ], "summary": "Read Property as of a watermark", "tags": [ "organization" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.property/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA single operated site — a hotel or resort, or a non-lodging business run on the same substrate (a standalone day spa). The property is the canonical home of most operational data and the anchor for local timezone, currency, and brand standards.", "operationId": "list_links_hospitality_property", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.property:read" ] } ], "summary": "List links of Property", "tags": [ "organization" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.block_for_property", "hospitality.link.board_sort_pattern_at_property", "hospitality.link.brand_has_property", "hospitality.link.brand_operator_cost_at_property", "hospitality.link.cancellation_policy_at_property", "hospitality.link.cashier_at_property", "hospitality.link.channel_commission_period_for_property", "hospitality.link.channel_connection_for_property", "hospitality.link.channel_for_property", "hospitality.link.checklist_template_at_property", "hospitality.link.commission_agreement_for_property", "hospitality.link.commission_batch_for_property", "hospitality.link.comp_authority_policy_at_property", "hospitality.link.demand_forecast_for_property", "hospitality.link.deposit_policy_at_property", "hospitality.link.desk_session_at_property", "hospitality.link.development_pathway_definition_at_property", "hospitality.link.device_at_property", "hospitality.link.fault_type_at_property", "hospitality.link.federated_participation_for_property", "hospitality.link.feedback_label_at_property", "hospitality.link.folio_routing_rule_at_property", "hospitality.link.fraud_assessment_at_property", "hospitality.link.fraud_network_contribution_at_property", "hospitality.link.fraud_network_signal_at_property", "hospitality.link.function_event_at_property", "hospitality.link.function_space_at_property", "hospitality.link.group_request_for_property", "hospitality.link.guest_conversation_at_property", "hospitality.link.housekeeping_briefing_at_property", "hospitality.link.housekeeping_credit_rule_at_property", "hospitality.link.incidental_hold_policy_at_property", "hospitality.link.ingredient_at_property", "hospitality.link.ingredient_supplier_price_at_property", "hospitality.link.labour_entry_at_property", "hospitality.link.loyalty_program_at_property", "hospitality.link.management_agreement_covers_property", "hospitality.link.material_at_property", "hospitality.link.membership_at_property", "hospitality.link.membership_grants_access_at_property", "hospitality.link.merchant_account_for_property", "hospitality.link.message_triage_at_property", "hospitality.link.no_show_posting_rule_at_property", "hospitality.link.outlet_at_property", "hospitality.link.owner_statement_for_property", "hospitality.link.package_at_property", "hospitality.link.pattern_at_property", "hospitality.link.portfolio_has_property", "hospitality.link.property_budget_for_property", "hospitality.link.property_has_availability_day", "hospitality.link.property_has_business_date", "hospitality.link.property_has_channel_mix_snapshot", "hospitality.link.property_has_design_dna", "hospitality.link.property_has_night_audit_run", "hospitality.link.property_has_philosophy", "hospitality.link.property_has_rate_plan", "hospitality.link.property_has_room", "hospitality.link.property_has_room_type", "hospitality.link.property_has_venue", "hospitality.link.property_owned_by_company", "hospitality.link.recipe_at_property", "hospitality.link.recognition_event_at_property", "hospitality.link.recommendation_at_property", "hospitality.link.recovery_pattern_run_for_property", "hospitality.link.reservation_for_property", "hospitality.link.restriction_recommendation_at_property", "hospitality.link.retail_product_available_at_property", "hospitality.link.round_template_at_property", "hospitality.link.run_for_property", "hospitality.link.sell_limit_recommendation_at_property", "hospitality.link.share_group_at_property", "hospitality.link.shift_at_property", "hospitality.link.staff_works_at_property", "hospitality.link.stay_offer_for_property", "hospitality.link.stock_store_at_property", "hospitality.link.stored_object_for_property", "hospitality.link.tax_rule_at_property", "hospitality.link.turnaway_for_property", "hospitality.link.utility_entry_at_property", "hospitality.link.venue_brand_originated_at_property", "hospitality.link.waitlist_entry_for_property" ] } } ] }, "/v1/object-types/hospitality.property/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA single operated site — a hotel or resort, or a non-lodging business run on the same substrate (a standalone day spa). The property is the canonical home of most operational data and the anchor for local timezone, currency, and brand standards.", "operationId": "traverse_hospitality_property", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.block_for_property", "hospitality.link.board_sort_pattern_at_property", "hospitality.link.brand_has_property", "hospitality.link.brand_operator_cost_at_property", "hospitality.link.cancellation_policy_at_property", "hospitality.link.cashier_at_property", "hospitality.link.channel_commission_period_for_property", "hospitality.link.channel_connection_for_property", "hospitality.link.channel_for_property", "hospitality.link.checklist_template_at_property", "hospitality.link.commission_agreement_for_property", "hospitality.link.commission_batch_for_property", "hospitality.link.comp_authority_policy_at_property", "hospitality.link.demand_forecast_for_property", "hospitality.link.deposit_policy_at_property", "hospitality.link.desk_session_at_property", "hospitality.link.development_pathway_definition_at_property", "hospitality.link.device_at_property", "hospitality.link.fault_type_at_property", "hospitality.link.federated_participation_for_property", "hospitality.link.feedback_label_at_property", "hospitality.link.folio_routing_rule_at_property", "hospitality.link.fraud_assessment_at_property", "hospitality.link.fraud_network_contribution_at_property", "hospitality.link.fraud_network_signal_at_property", "hospitality.link.function_event_at_property", "hospitality.link.function_space_at_property", "hospitality.link.group_request_for_property", "hospitality.link.guest_conversation_at_property", "hospitality.link.housekeeping_briefing_at_property", "hospitality.link.housekeeping_credit_rule_at_property", "hospitality.link.incidental_hold_policy_at_property", "hospitality.link.ingredient_at_property", "hospitality.link.ingredient_supplier_price_at_property", "hospitality.link.labour_entry_at_property", "hospitality.link.loyalty_program_at_property", "hospitality.link.management_agreement_covers_property", "hospitality.link.material_at_property", "hospitality.link.membership_at_property", "hospitality.link.membership_grants_access_at_property", "hospitality.link.merchant_account_for_property", "hospitality.link.message_triage_at_property", "hospitality.link.no_show_posting_rule_at_property", "hospitality.link.outlet_at_property", "hospitality.link.owner_statement_for_property", "hospitality.link.package_at_property", "hospitality.link.pattern_at_property", "hospitality.link.portfolio_has_property", "hospitality.link.property_budget_for_property", "hospitality.link.property_has_availability_day", "hospitality.link.property_has_business_date", "hospitality.link.property_has_channel_mix_snapshot", "hospitality.link.property_has_design_dna", "hospitality.link.property_has_night_audit_run", "hospitality.link.property_has_philosophy", "hospitality.link.property_has_rate_plan", "hospitality.link.property_has_room", "hospitality.link.property_has_room_type", "hospitality.link.property_has_venue", "hospitality.link.property_owned_by_company", "hospitality.link.recipe_at_property", "hospitality.link.recognition_event_at_property", "hospitality.link.recommendation_at_property", "hospitality.link.recovery_pattern_run_for_property", "hospitality.link.reservation_for_property", "hospitality.link.restriction_recommendation_at_property", "hospitality.link.retail_product_available_at_property", "hospitality.link.round_template_at_property", "hospitality.link.run_for_property", "hospitality.link.sell_limit_recommendation_at_property", "hospitality.link.share_group_at_property", "hospitality.link.shift_at_property", "hospitality.link.staff_works_at_property", "hospitality.link.stay_offer_for_property", "hospitality.link.stock_store_at_property", "hospitality.link.stored_object_for_property", "hospitality.link.tax_rule_at_property", "hospitality.link.turnaway_for_property", "hospitality.link.utility_entry_at_property", "hospitality.link.venue_brand_originated_at_property", "hospitality.link.waitlist_entry_for_property" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.property:read" ] } ], "summary": "Traverse from Property", "tags": [ "organization" ] } }, "/v1/object-types/hospitality.property/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA single operated site — a hotel or resort, or a non-lodging business run on the same substrate (a standalone day spa). The property is the canonical home of most operational data and the anchor for local timezone, currency, and brand standards.", "operationId": "search_hospitality_property", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "legal_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "legal_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "legal_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "legal_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "hotel", "resort", "residences", "serviced_apartments", "hostel", "glamping", "mixed_use", "day_spa", "restaurant" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "positioning" }, "type": { "const": "eq" }, "value": { "enum": [ "luxury", "upper_upscale", "upscale", "upper_midscale", "midscale", "economy", "boutique", "lifestyle" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "timezone" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "timezone" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "timezone" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "timezone" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "default_currency" }, "type": { "const": "eq" }, "value": { "format": "iso-4217", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "address" }, "type": { "const": "eq" }, "value": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "location" }, "type": { "const": "eq" }, "value": { "properties": { "lat": { "type": "number" }, "lon": { "type": "number" } }, "required": [ "lat", "lon" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "room_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "room_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "room_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_on" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_on" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "opened_on" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "standard_week_hours" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "standard_week_hours" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "standard_week_hours" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "star_rating" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "star_rating" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "star_rating" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "open_business_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "open_business_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "open_business_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date_opened_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date_opened_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date_opened_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "visitor_key_grace_days" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "visitor_key_grace_days" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "visitor_key_grace_days" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waitlist_offer_hold_minutes" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waitlist_offer_hold_minutes" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waitlist_offer_hold_minutes" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "request_soon_minutes" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "request_soon_minutes" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "request_soon_minutes" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waitlist_offer_messaging" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waitlist_claim_url_base" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waitlist_claim_url_base" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waitlist_claim_url_base" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "waitlist_claim_url_base" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_request_messaging" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_request_reuse_terms" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_request_reuse_terms" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "billing_identity" }, "type": { "const": "eq" }, "value": { "properties": { "bank_account": { "properties": { "account_name": { "type": "string" }, "account_number": { "type": "string" }, "bic": { "type": "string" }, "iban": { "type": "string" }, "sort_code": { "type": "string" } }, "type": "object" }, "company_registration_number": { "type": "string" }, "contact_email": { "type": "string" }, "contact_phone": { "type": "string" }, "invoice_address": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "type": "object" }, "invoice_issue_deadline_days": { "type": "integer" }, "invoice_number_prefix": { "type": "string" }, "payment_terms_days": { "type": "integer" }, "simplified_invoice_threshold": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "tax_registration_number": { "type": "string" }, "tax_registration_scheme": { "enum": [ "vat", "gst", "sales_tax", "none" ], "type": "string" } }, "required": [ "tax_registration_scheme" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "post_stay_charging_days" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "post_stay_charging_days" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "post_stay_charging_days" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_threshold" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_max_per_stay" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_max_per_stay" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_max_per_stay" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_interval_minutes" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_interval_minutes" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_interval_minutes" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "credit_limit_overage" }, "type": { "const": "eq" }, "value": { "enum": [ "off", "hold", "charge" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fnb_open_checks_at_roll" }, "type": { "const": "eq" }, "value": { "enum": [ "carry", "refuse" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sca_chase" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sca_chase_hours" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sca_chase_hours" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sca_chase_hours" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sca_chase_reminders" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sca_chase_reminders" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sca_chase_reminders" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "legal_name", "kind", "positioning", "timezone", "room_count", "opened_on", "standard_week_hours", "star_rating", "open_business_date", "business_date_opened_at", "visitor_key_grace_days", "waitlist_offer_hold_minutes", "request_soon_minutes", "waitlist_claim_url_base", "payment_request_reuse_terms", "description", "post_stay_charging_days", "hold_top_up_max_per_stay", "hold_top_up_interval_minutes", "credit_limit_overage", "fnb_open_checks_at_roll", "sca_chase_hours", "sca_chase_reminders" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property" }, "properties": { "additionalProperties": false, "properties": { "address": { "description": "Address", "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "title": "Property address", "type": "object" }, "billing_identity": { "description": "Who this property is, legally, on a document it issues. Absent until an operator fills it in, and `issue_invoice` refuses without it — a tax invoice with no supplier registration number is not one. Snapshotted onto every invoice at issue, so editing this never rewrites a document already handed over.", "properties": { "bank_account": { "properties": { "account_name": { "type": "string" }, "account_number": { "type": "string" }, "bic": { "type": "string" }, "iban": { "type": "string" }, "sort_code": { "type": "string" } }, "type": "object" }, "company_registration_number": { "type": "string" }, "contact_email": { "type": "string" }, "contact_phone": { "type": "string" }, "invoice_address": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string" } }, "required": [ "line1", "city", "country" ], "type": "object" }, "invoice_issue_deadline_days": { "type": "integer" }, "invoice_number_prefix": { "type": "string" }, "payment_terms_days": { "type": "integer" }, "simplified_invoice_threshold": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "tax_registration_number": { "type": "string" }, "tax_registration_scheme": { "enum": [ "vat", "gst", "sales_tax", "none" ], "type": "string" } }, "required": [ "tax_registration_scheme" ], "title": "Property billing identity", "type": "object" }, "business_date_opened_at": { "description": "When the open business date was opened. A posting stamped before this instant belongs to an earlier day and is dated by the property-local calendar instead.", "format": "date-time", "title": "Open business date opened at", "type": "string" }, "code": { "title": "Property code", "type": "string" }, "credit_limit_overage": { "enum": [ "off", "hold", "charge" ], "title": "What the night audit does once a stay's bill reaches what its holds are for: off, hold the excess, or charge (set_credit_limit_overage; off unset)", "type": "string" }, "default_currency": { "format": "iso-4217", "title": "Default currency (ISO 4217)", "type": "string" }, "description": { "title": "Description", "type": "string" }, "fnb_open_checks_at_roll": { "enum": [ "carry", "refuse" ], "title": "What the night audit does with the outlets' checks still open on the day it closes: carry them on their own business date, or refuse the close (set_fnb_open_checks_policy; carry unset)", "type": "string" }, "hold_top_up": { "title": "Whether the night audit tops up an in-house stay's card hold as its bill grows (set_hold_top_up; off unset)", "type": "boolean" }, "hold_top_up_interval_minutes": { "title": "How often, in minutes, the card rail plans the house's in-house stays' top-ups between night audits (60 to 1440; 0 or unset: at the audit and on the desk's press only)", "type": "integer" }, "hold_top_up_max_per_stay": { "title": "The most top-ups the card rail places for one stay", "type": "integer" }, "hold_top_up_threshold": { "description": "The smallest excess worth a top-up — the bill less what is held plus the rule's allowance", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Property hold top up threshold", "type": "object" }, "kind": { "enum": [ "hotel", "resort", "residences", "serviced_apartments", "hostel", "glamping", "mixed_use", "day_spa", "restaurant" ], "title": "Property kind", "type": "string" }, "legal_name": { "title": "Legal name", "type": "string" }, "location": { "properties": { "lat": { "type": "number" }, "lon": { "type": "number" } }, "required": [ "lat", "lon" ], "title": "Geo location", "type": "object" }, "name": { "title": "Property name", "type": "string" }, "open_business_date": { "description": "The business date this property has open — the hotel date a posting made now is dated to. Written by open_business_date and the night audit's close; unset while no day is open.", "format": "date", "title": "Open business date", "type": "string" }, "opened_on": { "format": "date", "title": "Opened on", "type": "string" }, "payment_request_messaging": { "description": "When true, a payment request's pay link is sent to the booking's guest — by email, or by SMS when the profile holds no email — as soon as the card rail has minted it. Unset: off, and the desk sends the link itself.", "title": "Send pay links to the guest", "type": "boolean" }, "payment_request_reuse_terms": { "description": "What the pay page tells the guest about keeping their card (Stripe's submit-button text, at most 1,200 characters): that the house may charge it without them present, for what, when and how often, and how each amount is set — the terms Stripe requires for a merchant-initiated charge. Set with `set_payment_request_messaging`. Unset: the card rail's default wording.", "title": "Pay page card terms", "type": "string" }, "positioning": { "enum": [ "luxury", "upper_upscale", "upscale", "upper_midscale", "midscale", "economy", "boutique", "lifestyle" ], "title": "Market positioning", "type": "string" }, "post_stay_charging_days": { "description": "How many business days after departure a charge found later (the minibar, damage, laundry) may still be posted to the departed stay's bill and taken from its card. On (1–14), check-out keeps the stay's largest card hold and releases the rest, and the window closes at the house's midnight after its last day — 1 is OPERA's \"until the end of the business date\". Off (0 or unset), check-out releases every hold. Set with `set_post_stay_charging`.", "title": "Post-stay charging window, in days (0 = off)", "type": "integer" }, "request_soon_minutes": { "description": "How many minutes before its due time a housekeeping request reads as `soon` on the housekeeping_requests read (and on the handset's card). Unset: 30. Between 1 and 720. Set through set_request_urgency_window.", "title": "Minutes ahead within which a request reads as soon", "type": "integer" }, "room_count": { "title": "Total rooms", "type": "integer" }, "sca_chase": { "description": "When true, a charge or hold the card rail tried with the guest absent that the issuer will only complete with the cardholder sends the guest a page to confirm it on (email first, else SMS, under the service-message consent gate), reminds them before the deadline, and tells the house when the deadline passes. Unset: off — the state and its deadline are still recorded and the desk sends the page itself. Set with `set_sca_chase`.", "title": "Chase a guest whose bank asks them to confirm", "type": "boolean" }, "sca_chase_hours": { "description": "The house's deadline for a pending authentication, in hours from the moment the issuer asked (1–168). Unset: 24.", "title": "Hours the guest has to confirm", "type": "integer" }, "sca_chase_reminders": { "description": "How many reminders go to the guest before the deadline, spread evenly across it (0–3; 1 is one at half-time). Unset: 1.", "title": "Reminders before the deadline", "type": "integer" }, "standard_week_hours": { "format": "decimal", "title": "Standard work week hours", "type": "string" }, "star_rating": { "format": "decimal", "title": "Star rating", "type": "string" }, "timezone": { "title": "IANA timezone", "type": "string" }, "visitor_key_grace_days": { "description": "How many days past a stay's arrival night the night audit keeps the booking engine's visitor key on its offers, turnaways and reservation before stripping it; the records themselves stay. Unset: 30. At most 365.", "title": "Days past the arrival night a visitor key is kept", "type": "integer" }, "waitlist_claim_url_base": { "description": "The start of the link a waitlist offer carries; the offer's claim token is appended as a path segment. Point it at the kernel's own claim page (`https:///v1/waitlist-claims/`) or at a booking site that calls the claim route. An https URL ending in `/`, with no query or fragment (plain http only to a loopback dev host). Unset: the offer goes out without a link and asks the guest to call.", "title": "Where a waitlist claim link points", "type": "string" }, "waitlist_offer_hold_minutes": { "description": "How many minutes a waitlist offer — the desk's or the matcher's — keeps its room-nights before they are given back and offered to the next entry. Unset: 30. Between 1 and 1440 (OPERA's room-hold range).", "title": "Minutes a waitlist offer keeps its room-nights", "type": "integer" }, "waitlist_offer_messaging": { "description": "When true, every waitlist offer — the desk's or the matcher's — is sent to the guest by SMS (or email when the profile holds no phone), with a link to claim it. Unset: off.", "title": "Send waitlist offers to the guest", "type": "boolean" } }, "required": [ "code", "name", "kind", "timezone", "default_currency" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.property:read" ] } ], "summary": "Search Property", "tags": [ "organization" ] } }, "/v1/object-types/hospitality.property_budget/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne fiscal year's operating budget for one property, submitted by the operator in the HMA's window (contract band: Oct 15 – Dec 1) and approved or objected to by the owner through an approval gate (implements `approvable`; `objected` is the PHR HMA's own vocabulary). Load-bearing beyond narrative: the owner statement's variance columns and the performance test's NOI prong are computed against it.", "operationId": "get_hospitality_property_budget", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property_budget" }, "properties": { "additionalProperties": false, "properties": { "budgeted_gop": { "description": "Budgeted gross operating profit", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Property budget budgeted gop", "type": "object" }, "budgeted_noi": { "description": "Budgeted net operating income (the performance test's denominator)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Property budget budgeted noi", "type": "object" }, "budgeted_revenue": { "description": "Budgeted total operating revenue", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Property budget budgeted revenue", "type": "object" }, "decided_at": { "format": "date-time", "title": "When the owner's gate decided", "type": "string" }, "external_ref": { "title": "External ref", "type": "string" }, "fiscal_year": { "title": "Fiscal year", "type": "integer" }, "id": { "title": "Budget id", "type": "string" }, "status": { "enum": [ "submitted", "approved", "objected" ], "title": "Lifecycle status", "type": "string" }, "submitted_at": { "format": "date-time", "title": "When the operator submitted", "type": "string" } }, "required": [ "id", "fiscal_year", "status", "budgeted_revenue", "submitted_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.property_budget:read" ] } ], "summary": "Read Property budget", "tags": [ "management" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.property_budget/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne fiscal year's operating budget for one property, submitted by the operator in the HMA's window (contract band: Oct 15 – Dec 1) and approved or objected to by the owner through an approval gate (implements `approvable`; `objected` is the PHR HMA's own vocabulary). Load-bearing beyond narrative: the owner statement's variance columns and the performance test's NOI prong are computed against it.", "operationId": "get_hospitality_property_budget_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.property_budget" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.property_budget:read" ] } ], "summary": "Read Property budget as of a watermark", "tags": [ "management" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.property_budget/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne fiscal year's operating budget for one property, submitted by the operator in the HMA's window (contract band: Oct 15 – Dec 1) and approved or objected to by the owner through an approval gate (implements `approvable`; `objected` is the PHR HMA's own vocabulary). Load-bearing beyond narrative: the owner statement's variance columns and the performance test's NOI prong are computed against it.", "operationId": "list_links_hospitality_property_budget", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.property_budget:read" ] } ], "summary": "List links of Property budget", "tags": [ "management" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.approval_gate_for_property_budget", "hospitality.link.property_budget_for_property" ] } } ] }, "/v1/object-types/hospitality.property_budget/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne fiscal year's operating budget for one property, submitted by the operator in the HMA's window (contract band: Oct 15 – Dec 1) and approved or objected to by the owner through an approval gate (implements `approvable`; `objected` is the PHR HMA's own vocabulary). Load-bearing beyond narrative: the owner statement's variance columns and the performance test's NOI prong are computed against it.", "operationId": "traverse_hospitality_property_budget", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.approval_gate_for_property_budget", "hospitality.link.property_budget_for_property" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.property_budget:read" ] } ], "summary": "Traverse from Property budget", "tags": [ "management" ] } }, "/v1/object-types/hospitality.property_budget/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne fiscal year's operating budget for one property, submitted by the operator in the HMA's window (contract band: Oct 15 – Dec 1) and approved or objected to by the owner through an approval gate (implements `approvable`; `objected` is the PHR HMA's own vocabulary). Load-bearing beyond narrative: the owner statement's variance columns and the performance test's NOI prong are computed against it.", "operationId": "search_hospitality_property_budget", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fiscal_year" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fiscal_year" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fiscal_year" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "submitted", "approved", "objected" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "budgeted_revenue" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "budgeted_gop" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "budgeted_noi" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "submitted_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "submitted_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "submitted_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "fiscal_year", "status", "submitted_at", "decided_at", "external_ref" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.property_budget" }, "properties": { "additionalProperties": false, "properties": { "budgeted_gop": { "description": "Budgeted gross operating profit", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Property budget budgeted gop", "type": "object" }, "budgeted_noi": { "description": "Budgeted net operating income (the performance test's denominator)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Property budget budgeted noi", "type": "object" }, "budgeted_revenue": { "description": "Budgeted total operating revenue", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Property budget budgeted revenue", "type": "object" }, "decided_at": { "format": "date-time", "title": "When the owner's gate decided", "type": "string" }, "external_ref": { "title": "External ref", "type": "string" }, "fiscal_year": { "title": "Fiscal year", "type": "integer" }, "id": { "title": "Budget id", "type": "string" }, "status": { "enum": [ "submitted", "approved", "objected" ], "title": "Lifecycle status", "type": "string" }, "submitted_at": { "format": "date-time", "title": "When the operator submitted", "type": "string" } }, "required": [ "id", "fiscal_year", "status", "budgeted_revenue", "submitted_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.property_budget:read" ] } ], "summary": "Search Property budget", "tags": [ "management" ] } }, "/v1/object-types/hospitality.proposed_action/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA frozen, auditable record of an action an agent intends to fire, surfaced for human/guest confirmation. Carries the target action name, the frozen proposed parameters, the rationale, and the context the agent saw. On `confirm_proposed_action` the kernel — not the agent — fires the chained typed action through the normal scope-checked, idempotency-keyed action surface; the agent never touches state directly (single-write-surface honesty, proposal 0030 §1). The `decision_*` / `applied_*` fields mutate exactly once on the transition out of `proposed`. Supersession is on the `proposed_action_superseded_by` self-link.", "operationId": "get_hospitality_proposed_action", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.proposed_action" }, "properties": { "additionalProperties": false, "properties": { "applied_action_correlation_id": { "title": "The chained typed action's correlation id — the audit-trail join", "type": "string" }, "applied_params": { "title": "The params actually fired on `applied` — may differ from `target_params_snapshot` when the confirmer edited them (the edit-rate trust signal, §7)" }, "applied_target_ref": { "title": "Id of the object the chained action created/modified", "type": "string" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Agent confidence in the proposal", "type": "string" }, "context_snapshot": { "title": "Frozen context the agent saw (the guest request, the disruption); bounded excerpts only — full content stays in the system of record" }, "decided_at": { "format": "date-time", "title": "Set on exit from `proposed`", "type": "string" }, "decided_by": { "title": "Principal::stable_id() of the confirming principal (guest surface, staff member, approval gate, or the expiry sweep)", "type": "string" }, "decision_status": { "enum": [ "proposed", "applied", "rejected", "expired", "superseded" ], "title": "Frozen-artefact lifecycle status", "type": "string" }, "expires_at": { "format": "date-time", "title": "When an unconfirmed proposal sweeps to `expired` (default 24h)", "type": "string" }, "id": { "title": "Proposal id", "type": "string" }, "proposed_by": { "title": "Principal::stable_id() of the proposing agent — the audit anchor", "type": "string" }, "rationale_text": { "title": "Human-readable 'why', surfaced at confirmation time", "type": "string" }, "rejection_reason": { "title": "Set on `rejected`", "type": "string" }, "requires_confirmation_from": { "enum": [ "guest", "staff", "approval_gate" ], "title": "Who must confirm before the kernel fires the action", "type": "string" }, "subject_kind": { "enum": [ "reservation", "person", "folio", "charge", "stay", "venue", "other" ], "title": "The object class the action targets", "type": "string" }, "subject_ref": { "title": "Id of the subject object (resolved against `subject_kind`)", "type": "string" }, "target_action": { "title": "The registered action this proposal intends to fire (ApiName form); validated against the registry", "type": "string" }, "target_params_snapshot": { "title": "Frozen proposed parameters for `target_action` — the audit-grade record of what the agent wanted to do" } }, "required": [ "id", "proposed_by", "target_action", "subject_kind", "subject_ref", "confidence", "requires_confirmation_from", "expires_at", "decision_status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.proposed_action:read" ] } ], "summary": "Read Proposed action", "tags": [ "proposed_action" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.proposed_action/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA frozen, auditable record of an action an agent intends to fire, surfaced for human/guest confirmation. Carries the target action name, the frozen proposed parameters, the rationale, and the context the agent saw. On `confirm_proposed_action` the kernel — not the agent — fires the chained typed action through the normal scope-checked, idempotency-keyed action surface; the agent never touches state directly (single-write-surface honesty, proposal 0030 §1). The `decision_*` / `applied_*` fields mutate exactly once on the transition out of `proposed`. Supersession is on the `proposed_action_superseded_by` self-link.", "operationId": "get_hospitality_proposed_action_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.proposed_action" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.proposed_action:read" ] } ], "summary": "Read Proposed action as of a watermark", "tags": [ "proposed_action" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.proposed_action/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA frozen, auditable record of an action an agent intends to fire, surfaced for human/guest confirmation. Carries the target action name, the frozen proposed parameters, the rationale, and the context the agent saw. On `confirm_proposed_action` the kernel — not the agent — fires the chained typed action through the normal scope-checked, idempotency-keyed action surface; the agent never touches state directly (single-write-surface honesty, proposal 0030 §1). The `decision_*` / `applied_*` fields mutate exactly once on the transition out of `proposed`. Supersession is on the `proposed_action_superseded_by` self-link.", "operationId": "list_links_hospitality_proposed_action", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.proposed_action:read" ] } ], "summary": "List links of Proposed action", "tags": [ "proposed_action" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.proposed_action_confirmed_via_approval", "hospitality.link.proposed_action_for_conversation", "hospitality.link.proposed_action_superseded_by" ] } } ] }, "/v1/object-types/hospitality.proposed_action/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA frozen, auditable record of an action an agent intends to fire, surfaced for human/guest confirmation. Carries the target action name, the frozen proposed parameters, the rationale, and the context the agent saw. On `confirm_proposed_action` the kernel — not the agent — fires the chained typed action through the normal scope-checked, idempotency-keyed action surface; the agent never touches state directly (single-write-surface honesty, proposal 0030 §1). The `decision_*` / `applied_*` fields mutate exactly once on the transition out of `proposed`. Supersession is on the `proposed_action_superseded_by` self-link.", "operationId": "traverse_hospitality_proposed_action", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.proposed_action_confirmed_via_approval", "hospitality.link.proposed_action_for_conversation", "hospitality.link.proposed_action_superseded_by" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.proposed_action:read" ] } ], "summary": "Traverse from Proposed action", "tags": [ "proposed_action" ] } }, "/v1/object-types/hospitality.proposed_action/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA frozen, auditable record of an action an agent intends to fire, surfaced for human/guest confirmation. Carries the target action name, the frozen proposed parameters, the rationale, and the context the agent saw. On `confirm_proposed_action` the kernel — not the agent — fires the chained typed action through the normal scope-checked, idempotency-keyed action surface; the agent never touches state directly (single-write-surface honesty, proposal 0030 §1). The `decision_*` / `applied_*` fields mutate exactly once on the transition out of `proposed`. Supersession is on the `proposed_action_superseded_by` self-link.", "operationId": "search_hospitality_proposed_action", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "proposed_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "proposed_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "proposed_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "proposed_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_action" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_action" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_action" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_action" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_params_snapshot" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "subject_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "reservation", "person", "folio", "charge", "stay", "venue", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "subject_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "subject_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "subject_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "subject_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rationale_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rationale_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "context_snapshot" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confidence" }, "type": { "const": "eq" }, "value": { "enum": [ "low", "medium", "high" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requires_confirmation_from" }, "type": { "const": "eq" }, "value": { "enum": [ "guest", "staff", "approval_gate" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decision_status" }, "type": { "const": "eq" }, "value": { "enum": [ "proposed", "applied", "rejected", "expired", "superseded" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_params" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_action_correlation_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_action_correlation_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_action_correlation_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_action_correlation_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_target_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_target_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_target_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_target_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejection_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejection_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "proposed_by", "target_action", "subject_kind", "subject_ref", "rationale_text", "confidence", "requires_confirmation_from", "expires_at", "decision_status", "decided_at", "decided_by", "applied_action_correlation_id", "applied_target_ref", "rejection_reason" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.proposed_action" }, "properties": { "additionalProperties": false, "properties": { "applied_action_correlation_id": { "title": "The chained typed action's correlation id — the audit-trail join", "type": "string" }, "applied_params": { "title": "The params actually fired on `applied` — may differ from `target_params_snapshot` when the confirmer edited them (the edit-rate trust signal, §7)" }, "applied_target_ref": { "title": "Id of the object the chained action created/modified", "type": "string" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Agent confidence in the proposal", "type": "string" }, "context_snapshot": { "title": "Frozen context the agent saw (the guest request, the disruption); bounded excerpts only — full content stays in the system of record" }, "decided_at": { "format": "date-time", "title": "Set on exit from `proposed`", "type": "string" }, "decided_by": { "title": "Principal::stable_id() of the confirming principal (guest surface, staff member, approval gate, or the expiry sweep)", "type": "string" }, "decision_status": { "enum": [ "proposed", "applied", "rejected", "expired", "superseded" ], "title": "Frozen-artefact lifecycle status", "type": "string" }, "expires_at": { "format": "date-time", "title": "When an unconfirmed proposal sweeps to `expired` (default 24h)", "type": "string" }, "id": { "title": "Proposal id", "type": "string" }, "proposed_by": { "title": "Principal::stable_id() of the proposing agent — the audit anchor", "type": "string" }, "rationale_text": { "title": "Human-readable 'why', surfaced at confirmation time", "type": "string" }, "rejection_reason": { "title": "Set on `rejected`", "type": "string" }, "requires_confirmation_from": { "enum": [ "guest", "staff", "approval_gate" ], "title": "Who must confirm before the kernel fires the action", "type": "string" }, "subject_kind": { "enum": [ "reservation", "person", "folio", "charge", "stay", "venue", "other" ], "title": "The object class the action targets", "type": "string" }, "subject_ref": { "title": "Id of the subject object (resolved against `subject_kind`)", "type": "string" }, "target_action": { "title": "The registered action this proposal intends to fire (ApiName form); validated against the registry", "type": "string" }, "target_params_snapshot": { "title": "Frozen proposed parameters for `target_action` — the audit-grade record of what the agent wanted to do" } }, "required": [ "id", "proposed_by", "target_action", "subject_kind", "subject_ref", "confidence", "requires_confirmation_from", "expires_at", "decision_status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.proposed_action:read" ] } ], "summary": "Search Proposed action", "tags": [ "proposed_action" ] } }, "/v1/object-types/hospitality.public_area/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA place in the house that is not a guest room — a lobby, a corridor, a lift, the pool, the gym, the staff canteen — whose cleaning and inspection are housekeeping tasks linked `housekeeping_task_for_area` (hubOS's common zones). `code` is the house's business key for it (`register_public_area` upserts by it); `kind` is what a checklist template names (`applies_to_area_kind`), so every corridor shares one list; `reader_code` is what its QR / NFC reader carries, unique in the house across rooms and areas (`set_public_area_reader_code`) — the handset scans it and asks the object search for an `eq` on `reader_code`. An `active` area gets one `public_area_clean` per business date from `generate_housekeeping_tasks`; a `retired` one gets nothing and carries no reader code.", "operationId": "get_hospitality_public_area", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.public_area" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "The house's code for the area (\"LOBBY\", \"C3-EAST\")", "type": "string" }, "floor": { "title": "The floor it is on, in the rooms' own words (a room's `floor`)", "type": "string" }, "kind": { "enum": [ "lobby", "corridor", "lift", "stairwell", "pool", "gym", "spa_area", "restaurant_floor", "toilets", "back_of_house", "exterior", "other" ], "title": "What kind of place it is — what a checklist template names", "type": "string" }, "name": { "title": "What the floor calls it (\"Main lobby\", \"Third-floor corridor, east\")", "type": "string" }, "reader_code": { "title": "The code the area's QR / NFC reader carries (unique within the property, across rooms and areas)", "type": "string" }, "retired_at": { "format": "date-time", "title": "When the area was retired (present while retired)", "type": "string" }, "status": { "enum": [ "active", "retired" ], "title": "Active (cleaned daily, scannable) or retired", "type": "string" } }, "required": [ "code", "name", "kind", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.public_area:read" ] } ], "summary": "Read Public area", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.public_area/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA place in the house that is not a guest room — a lobby, a corridor, a lift, the pool, the gym, the staff canteen — whose cleaning and inspection are housekeeping tasks linked `housekeeping_task_for_area` (hubOS's common zones). `code` is the house's business key for it (`register_public_area` upserts by it); `kind` is what a checklist template names (`applies_to_area_kind`), so every corridor shares one list; `reader_code` is what its QR / NFC reader carries, unique in the house across rooms and areas (`set_public_area_reader_code`) — the handset scans it and asks the object search for an `eq` on `reader_code`. An `active` area gets one `public_area_clean` per business date from `generate_housekeeping_tasks`; a `retired` one gets nothing and carries no reader code.", "operationId": "get_hospitality_public_area_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.public_area" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.public_area:read" ] } ], "summary": "Read Public area as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.public_area/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA place in the house that is not a guest room — a lobby, a corridor, a lift, the pool, the gym, the staff canteen — whose cleaning and inspection are housekeeping tasks linked `housekeeping_task_for_area` (hubOS's common zones). `code` is the house's business key for it (`register_public_area` upserts by it); `kind` is what a checklist template names (`applies_to_area_kind`), so every corridor shares one list; `reader_code` is what its QR / NFC reader carries, unique in the house across rooms and areas (`set_public_area_reader_code`) — the handset scans it and asks the object search for an `eq` on `reader_code`. An `active` area gets one `public_area_clean` per business date from `generate_housekeeping_tasks`; a `retired` one gets nothing and carries no reader code.", "operationId": "list_links_hospitality_public_area", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.public_area:read" ] } ], "summary": "List links of Public area", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.housekeeping_task_for_area", "hospitality.link.work_order_for_area" ] } } ] }, "/v1/object-types/hospitality.public_area/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA place in the house that is not a guest room — a lobby, a corridor, a lift, the pool, the gym, the staff canteen — whose cleaning and inspection are housekeeping tasks linked `housekeeping_task_for_area` (hubOS's common zones). `code` is the house's business key for it (`register_public_area` upserts by it); `kind` is what a checklist template names (`applies_to_area_kind`), so every corridor shares one list; `reader_code` is what its QR / NFC reader carries, unique in the house across rooms and areas (`set_public_area_reader_code`) — the handset scans it and asks the object search for an `eq` on `reader_code`. An `active` area gets one `public_area_clean` per business date from `generate_housekeeping_tasks`; a `retired` one gets nothing and carries no reader code.", "operationId": "traverse_hospitality_public_area", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.housekeeping_task_for_area", "hospitality.link.work_order_for_area" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.public_area:read" ] } ], "summary": "Traverse from Public area", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.public_area/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA place in the house that is not a guest room — a lobby, a corridor, a lift, the pool, the gym, the staff canteen — whose cleaning and inspection are housekeeping tasks linked `housekeeping_task_for_area` (hubOS's common zones). `code` is the house's business key for it (`register_public_area` upserts by it); `kind` is what a checklist template names (`applies_to_area_kind`), so every corridor shares one list; `reader_code` is what its QR / NFC reader carries, unique in the house across rooms and areas (`set_public_area_reader_code`) — the handset scans it and asks the object search for an `eq` on `reader_code`. An `active` area gets one `public_area_clean` per business date from `generate_housekeeping_tasks`; a `retired` one gets nothing and carries no reader code.", "operationId": "search_hospitality_public_area", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "lobby", "corridor", "lift", "stairwell", "pool", "gym", "spa_area", "restaurant_floor", "toilets", "back_of_house", "exterior", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "floor" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "floor" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "floor" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "floor" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reader_code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reader_code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reader_code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reader_code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "retired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "kind", "floor", "reader_code", "status", "retired_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.public_area" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "The house's code for the area (\"LOBBY\", \"C3-EAST\")", "type": "string" }, "floor": { "title": "The floor it is on, in the rooms' own words (a room's `floor`)", "type": "string" }, "kind": { "enum": [ "lobby", "corridor", "lift", "stairwell", "pool", "gym", "spa_area", "restaurant_floor", "toilets", "back_of_house", "exterior", "other" ], "title": "What kind of place it is — what a checklist template names", "type": "string" }, "name": { "title": "What the floor calls it (\"Main lobby\", \"Third-floor corridor, east\")", "type": "string" }, "reader_code": { "title": "The code the area's QR / NFC reader carries (unique within the property, across rooms and areas)", "type": "string" }, "retired_at": { "format": "date-time", "title": "When the area was retired (present while retired)", "type": "string" }, "status": { "enum": [ "active", "retired" ], "title": "Active (cleaned daily, scannable) or retired", "type": "string" } }, "required": [ "code", "name", "kind", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.public_area:read" ] } ], "summary": "Search Public area", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.purpose_grant/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne principal's hold on an `access_purpose`: requested with a recorded rationale, approved through an ordinary 0020 approval gate (the grant implements the `approvable` interface; the gate decision transitions it), alive until `expires_at` (the §9.1 sweep expires it — the grant implements `expirable`) or an operator revocation. Terminal grants are kept: the row is the audit answer to `who could touch this marking, under what purpose, on whose approval, and why`.", "operationId": "get_hospitality_purpose_grant", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.purpose_grant" }, "properties": { "additionalProperties": false, "properties": { "decided_at": { "format": "date-time", "title": "When the approval gate decided (or an operator revoked)", "type": "string" }, "expires_at": { "format": "date-time", "title": "When an `active` grant lapses (the expiry sweep transitions it); bounded by the purpose's `max_grant_hours`", "type": "string" }, "external_reference": { "title": "Opaque ref to the driving case (ticket, investigation, DSAR)", "type": "string" }, "id": { "title": "Grant id", "type": "string" }, "principal_id": { "title": "The holding principal's stable id (`user:` / `service:` / `agent:/@`)", "type": "string" }, "purpose_ref": { "title": "Business id of the `access_purpose` this grant confers (also linked via `purpose_grant_for_purpose`)", "type": "string" }, "rationale_text": { "title": "The requester's recorded rationale — why this principal needs this purpose now. The PBAC audit artefact; bounded prose, not a ticket link (put references in external_reference)", "type": "string" }, "requested_at": { "format": "date-time", "title": "When the grant was requested", "type": "string" }, "status": { "enum": [ "requested", "active", "rejected", "revoked", "expired" ], "title": "Lifecycle status", "type": "string" } }, "required": [ "id", "purpose_ref", "requested_at", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.purpose_grant:read" ] } ], "summary": "Read Purpose grant", "tags": [ "pbac" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.purpose_grant/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne principal's hold on an `access_purpose`: requested with a recorded rationale, approved through an ordinary 0020 approval gate (the grant implements the `approvable` interface; the gate decision transitions it), alive until `expires_at` (the §9.1 sweep expires it — the grant implements `expirable`) or an operator revocation. Terminal grants are kept: the row is the audit answer to `who could touch this marking, under what purpose, on whose approval, and why`.", "operationId": "get_hospitality_purpose_grant_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.purpose_grant" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.purpose_grant:read" ] } ], "summary": "Read Purpose grant as of a watermark", "tags": [ "pbac" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.purpose_grant/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne principal's hold on an `access_purpose`: requested with a recorded rationale, approved through an ordinary 0020 approval gate (the grant implements the `approvable` interface; the gate decision transitions it), alive until `expires_at` (the §9.1 sweep expires it — the grant implements `expirable`) or an operator revocation. Terminal grants are kept: the row is the audit answer to `who could touch this marking, under what purpose, on whose approval, and why`.", "operationId": "list_links_hospitality_purpose_grant", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.purpose_grant:read" ] } ], "summary": "List links of Purpose grant", "tags": [ "pbac" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.approval_gate_for_purpose_grant", "hospitality.link.purpose_grant_for_purpose" ] } } ] }, "/v1/object-types/hospitality.purpose_grant/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne principal's hold on an `access_purpose`: requested with a recorded rationale, approved through an ordinary 0020 approval gate (the grant implements the `approvable` interface; the gate decision transitions it), alive until `expires_at` (the §9.1 sweep expires it — the grant implements `expirable`) or an operator revocation. Terminal grants are kept: the row is the audit answer to `who could touch this marking, under what purpose, on whose approval, and why`.", "operationId": "traverse_hospitality_purpose_grant", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.approval_gate_for_purpose_grant", "hospitality.link.purpose_grant_for_purpose" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.purpose_grant:read" ] } ], "summary": "Traverse from Purpose grant", "tags": [ "pbac" ] } }, "/v1/object-types/hospitality.purpose_grant/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne principal's hold on an `access_purpose`: requested with a recorded rationale, approved through an ordinary 0020 approval gate (the grant implements the `approvable` interface; the gate decision transitions it), alive until `expires_at` (the §9.1 sweep expires it — the grant implements `expirable`) or an operator revocation. Terminal grants are kept: the row is the audit answer to `who could touch this marking, under what purpose, on whose approval, and why`.", "operationId": "search_hospitality_purpose_grant", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "purpose_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "purpose_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "purpose_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "purpose_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "principal_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "principal_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "principal_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "principal_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rationale_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rationale_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "requested", "active", "rejected", "revoked", "expired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "purpose_ref", "principal_id", "rationale_text", "external_reference", "requested_at", "expires_at", "status", "decided_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.purpose_grant" }, "properties": { "additionalProperties": false, "properties": { "decided_at": { "format": "date-time", "title": "When the approval gate decided (or an operator revoked)", "type": "string" }, "expires_at": { "format": "date-time", "title": "When an `active` grant lapses (the expiry sweep transitions it); bounded by the purpose's `max_grant_hours`", "type": "string" }, "external_reference": { "title": "Opaque ref to the driving case (ticket, investigation, DSAR)", "type": "string" }, "id": { "title": "Grant id", "type": "string" }, "principal_id": { "title": "The holding principal's stable id (`user:` / `service:` / `agent:/@`)", "type": "string" }, "purpose_ref": { "title": "Business id of the `access_purpose` this grant confers (also linked via `purpose_grant_for_purpose`)", "type": "string" }, "rationale_text": { "title": "The requester's recorded rationale — why this principal needs this purpose now. The PBAC audit artefact; bounded prose, not a ticket link (put references in external_reference)", "type": "string" }, "requested_at": { "format": "date-time", "title": "When the grant was requested", "type": "string" }, "status": { "enum": [ "requested", "active", "rejected", "revoked", "expired" ], "title": "Lifecycle status", "type": "string" } }, "required": [ "id", "purpose_ref", "requested_at", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.purpose_grant:read" ] } ], "summary": "Search Purpose grant", "tags": [ "pbac" ] } }, "/v1/object-types/hospitality.rail_instruction/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne thing the card rail is to do at the processor once it can be reached again — OPERA's offline settlement queue. Written by the rail (`queue_rail_instruction`) when the processor was unreachable (a transport failure, a 5xx, a 429) during a deferrable verb: a hold captured at check-out (`capture`), a hold released (`void`), a refund (`refund`), a departed stay's late charges (`charge_off_session`), the desk's Top up now for an in-house stay (`top_up`, continuing the stay's open top-up attempt). Never a check-in's authorisation — that hold is placed because the desk needs the answer now. `attempt_id` is written before the processor is asked again and every processor idempotency key for the instruction derives from it, so a retry is the same request and a capture that reached the processor once is never taken twice. The rail's drain claims it (`sending`), asks the processor, and records the outcome through the same ledger verbs the online path uses: `done`; `refused` with the processor's words, never retried; or `queued` again with an exponential backoff (`not_before`) until the cap or the key's window, then `abandoned` for the GM. A processor that replayed a saved failure under the key has spent that attempt: what it did is read back, and when nothing moved the instruction is queued again under a new `attempt_id`. The desk may take a `queued` one back (`cancel_rail_instruction` → `cancelled`), never one the drain is sending. The night audit drains whatever is queued, and its close lists what is still open.", "operationId": "get_hospitality_rail_instruction", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rail_instruction" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "What it moves: the capture to take, the hold to release, the refund to give, the collection asked for", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Rail instruction amount", "type": "object" }, "attempt_id": { "title": "The persisted attempt every processor idempotency key for the instruction derives from — a refund's is the key its online attempt was sent under, a collection's the stay's open collection attempt", "type": "string" }, "attempts": { "title": "How many times the drain has asked the processor", "type": "integer" }, "finished_at": { "format": "date-time", "title": "When it was done, refused, abandoned or cancelled", "type": "string" }, "id": { "title": "Rail instruction id", "type": "string" }, "kind": { "enum": [ "capture", "void", "refund", "charge_off_session", "top_up" ], "title": "capture, void, refund, charge_off_session or top_up", "type": "string" }, "last_attempt_at": { "format": "date-time", "title": "When the drain last asked the processor", "type": "string" }, "not_before": { "format": "date-time", "title": "When the drain may ask again — the backoff after an unreachable rail", "type": "string" }, "outcome_detail": { "title": "What the instruction came to, in the rail's words", "type": "string" }, "payment_id": { "title": "The payment a capture, release or refund acts on (its object id) — the rail_instruction_for_payment edge's target", "type": "string" }, "processor_words": { "title": "The processor's last words: its refusal, or the kind of failure that kept it from being reached — processor handles left out", "type": "string" }, "property_id": { "title": "The house the instruction is for (its object id)", "type": "string" }, "queued_at": { "format": "date-time", "title": "When the rail wrote the instruction down", "type": "string" }, "queued_because": { "title": "What kind of failure the rail met when the instruction was written (`server_error (503)`, `timeout`, …) — a kind, never the request path, which names the processor's handle", "type": "string" }, "queued_by": { "title": "Who asked for it: the principal the queued request carried (its JSON), under whose name the drain records the ledger's leg — the online attempt's, not the rail's (F4, 2026-10-19)", "type": "string" }, "refund_reason": { "enum": [ "duplicate", "fraudulent", "requested_by_customer", "reservation_cancelled", "deposit_return", "service_recovery", "overcharge_correction", "no_show_policy_exception", "package_component_refund", "membership_cancellation", "chargeback_prevention", "other" ], "title": "Why a queued refund gives money back", "type": "string" }, "result_payment_id": { "title": "The payment row the outcome recorded, when it made one (a refund's leg)", "type": "string" }, "reverse_transfer": { "title": "Whether a queued refund pulls the hotel's transfer back — the online attempt's form, kept so the drained retry under the same key is the same request (F4, 2026-10-19)", "type": "boolean" }, "state": { "enum": [ "queued", "sending", "done", "refused", "abandoned", "cancelled" ], "title": "queued, sending, done, refused, abandoned or cancelled", "type": "string" }, "stay_id": { "title": "The stay a collection or a top-up is for (its object id) — the rail_instruction_for_stay edge's target", "type": "string" }, "void_reason": { "enum": [ "duplicate", "fraudulent", "requested_by_customer", "abandoned", "review_declined", "authorisation_expired", "reservation_cancelled", "guest_disputed_pre_arrival", "released_at_departure" ], "title": "Why a queued release releases the hold (the void's reason)", "type": "string" } }, "required": [ "id", "kind", "state", "property_id", "amount", "attempt_id", "attempts", "not_before", "queued_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rail_instruction:read" ] } ], "summary": "Read Rail instruction", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.rail_instruction/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne thing the card rail is to do at the processor once it can be reached again — OPERA's offline settlement queue. Written by the rail (`queue_rail_instruction`) when the processor was unreachable (a transport failure, a 5xx, a 429) during a deferrable verb: a hold captured at check-out (`capture`), a hold released (`void`), a refund (`refund`), a departed stay's late charges (`charge_off_session`), the desk's Top up now for an in-house stay (`top_up`, continuing the stay's open top-up attempt). Never a check-in's authorisation — that hold is placed because the desk needs the answer now. `attempt_id` is written before the processor is asked again and every processor idempotency key for the instruction derives from it, so a retry is the same request and a capture that reached the processor once is never taken twice. The rail's drain claims it (`sending`), asks the processor, and records the outcome through the same ledger verbs the online path uses: `done`; `refused` with the processor's words, never retried; or `queued` again with an exponential backoff (`not_before`) until the cap or the key's window, then `abandoned` for the GM. A processor that replayed a saved failure under the key has spent that attempt: what it did is read back, and when nothing moved the instruction is queued again under a new `attempt_id`. The desk may take a `queued` one back (`cancel_rail_instruction` → `cancelled`), never one the drain is sending. The night audit drains whatever is queued, and its close lists what is still open.", "operationId": "get_hospitality_rail_instruction_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.rail_instruction" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rail_instruction:read" ] } ], "summary": "Read Rail instruction as of a watermark", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.rail_instruction/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne thing the card rail is to do at the processor once it can be reached again — OPERA's offline settlement queue. Written by the rail (`queue_rail_instruction`) when the processor was unreachable (a transport failure, a 5xx, a 429) during a deferrable verb: a hold captured at check-out (`capture`), a hold released (`void`), a refund (`refund`), a departed stay's late charges (`charge_off_session`), the desk's Top up now for an in-house stay (`top_up`, continuing the stay's open top-up attempt). Never a check-in's authorisation — that hold is placed because the desk needs the answer now. `attempt_id` is written before the processor is asked again and every processor idempotency key for the instruction derives from it, so a retry is the same request and a capture that reached the processor once is never taken twice. The rail's drain claims it (`sending`), asks the processor, and records the outcome through the same ledger verbs the online path uses: `done`; `refused` with the processor's words, never retried; or `queued` again with an exponential backoff (`not_before`) until the cap or the key's window, then `abandoned` for the GM. A processor that replayed a saved failure under the key has spent that attempt: what it did is read back, and when nothing moved the instruction is queued again under a new `attempt_id`. The desk may take a `queued` one back (`cancel_rail_instruction` → `cancelled`), never one the drain is sending. The night audit drains whatever is queued, and its close lists what is still open.", "operationId": "list_links_hospitality_rail_instruction", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rail_instruction:read" ] } ], "summary": "List links of Rail instruction", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.rail_instruction_for_payment", "hospitality.link.rail_instruction_for_stay" ] } } ] }, "/v1/object-types/hospitality.rail_instruction/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne thing the card rail is to do at the processor once it can be reached again — OPERA's offline settlement queue. Written by the rail (`queue_rail_instruction`) when the processor was unreachable (a transport failure, a 5xx, a 429) during a deferrable verb: a hold captured at check-out (`capture`), a hold released (`void`), a refund (`refund`), a departed stay's late charges (`charge_off_session`), the desk's Top up now for an in-house stay (`top_up`, continuing the stay's open top-up attempt). Never a check-in's authorisation — that hold is placed because the desk needs the answer now. `attempt_id` is written before the processor is asked again and every processor idempotency key for the instruction derives from it, so a retry is the same request and a capture that reached the processor once is never taken twice. The rail's drain claims it (`sending`), asks the processor, and records the outcome through the same ledger verbs the online path uses: `done`; `refused` with the processor's words, never retried; or `queued` again with an exponential backoff (`not_before`) until the cap or the key's window, then `abandoned` for the GM. A processor that replayed a saved failure under the key has spent that attempt: what it did is read back, and when nothing moved the instruction is queued again under a new `attempt_id`. The desk may take a `queued` one back (`cancel_rail_instruction` → `cancelled`), never one the drain is sending. The night audit drains whatever is queued, and its close lists what is still open.", "operationId": "traverse_hospitality_rail_instruction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.rail_instruction_for_payment", "hospitality.link.rail_instruction_for_stay" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rail_instruction:read" ] } ], "summary": "Traverse from Rail instruction", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.rail_instruction/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne thing the card rail is to do at the processor once it can be reached again — OPERA's offline settlement queue. Written by the rail (`queue_rail_instruction`) when the processor was unreachable (a transport failure, a 5xx, a 429) during a deferrable verb: a hold captured at check-out (`capture`), a hold released (`void`), a refund (`refund`), a departed stay's late charges (`charge_off_session`), the desk's Top up now for an in-house stay (`top_up`, continuing the stay's open top-up attempt). Never a check-in's authorisation — that hold is placed because the desk needs the answer now. `attempt_id` is written before the processor is asked again and every processor idempotency key for the instruction derives from it, so a retry is the same request and a capture that reached the processor once is never taken twice. The rail's drain claims it (`sending`), asks the processor, and records the outcome through the same ledger verbs the online path uses: `done`; `refused` with the processor's words, never retried; or `queued` again with an exponential backoff (`not_before`) until the cap or the key's window, then `abandoned` for the GM. A processor that replayed a saved failure under the key has spent that attempt: what it did is read back, and when nothing moved the instruction is queued again under a new `attempt_id`. The desk may take a `queued` one back (`cancel_rail_instruction` → `cancelled`), never one the drain is sending. The night audit drains whatever is queued, and its close lists what is still open.", "operationId": "search_hospitality_rail_instruction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "capture", "void", "refund", "charge_off_session", "top_up" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "state" }, "type": { "const": "eq" }, "value": { "enum": [ "queued", "sending", "done", "refused", "abandoned", "cancelled" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "payment_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "stay_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "stay_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "stay_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "stay_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "property_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "property_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "property_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "property_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "attempt_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "attempt_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "attempt_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "attempt_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "void_reason" }, "type": { "const": "eq" }, "value": { "enum": [ "duplicate", "fraudulent", "requested_by_customer", "abandoned", "review_declined", "authorisation_expired", "reservation_cancelled", "guest_disputed_pre_arrival", "released_at_departure" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "refund_reason" }, "type": { "const": "eq" }, "value": { "enum": [ "duplicate", "fraudulent", "requested_by_customer", "reservation_cancelled", "deposit_return", "service_recovery", "overcharge_correction", "no_show_policy_exception", "package_component_refund", "membership_cancellation", "chargeback_prevention", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reverse_transfer" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "queued_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "queued_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "attempts" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "attempts" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "attempts" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "not_before" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "not_before" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "not_before" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "queued_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "queued_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "queued_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_attempt_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_attempt_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_attempt_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "finished_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "finished_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "finished_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "queued_because" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "queued_because" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "processor_words" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "processor_words" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "outcome_detail" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "outcome_detail" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "result_payment_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "result_payment_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "result_payment_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "result_payment_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "kind", "state", "payment_id", "stay_id", "property_id", "attempt_id", "void_reason", "refund_reason", "queued_by", "attempts", "not_before", "queued_at", "last_attempt_at", "finished_at", "queued_because", "processor_words", "outcome_detail", "result_payment_id" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rail_instruction" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "What it moves: the capture to take, the hold to release, the refund to give, the collection asked for", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Rail instruction amount", "type": "object" }, "attempt_id": { "title": "The persisted attempt every processor idempotency key for the instruction derives from — a refund's is the key its online attempt was sent under, a collection's the stay's open collection attempt", "type": "string" }, "attempts": { "title": "How many times the drain has asked the processor", "type": "integer" }, "finished_at": { "format": "date-time", "title": "When it was done, refused, abandoned or cancelled", "type": "string" }, "id": { "title": "Rail instruction id", "type": "string" }, "kind": { "enum": [ "capture", "void", "refund", "charge_off_session", "top_up" ], "title": "capture, void, refund, charge_off_session or top_up", "type": "string" }, "last_attempt_at": { "format": "date-time", "title": "When the drain last asked the processor", "type": "string" }, "not_before": { "format": "date-time", "title": "When the drain may ask again — the backoff after an unreachable rail", "type": "string" }, "outcome_detail": { "title": "What the instruction came to, in the rail's words", "type": "string" }, "payment_id": { "title": "The payment a capture, release or refund acts on (its object id) — the rail_instruction_for_payment edge's target", "type": "string" }, "processor_words": { "title": "The processor's last words: its refusal, or the kind of failure that kept it from being reached — processor handles left out", "type": "string" }, "property_id": { "title": "The house the instruction is for (its object id)", "type": "string" }, "queued_at": { "format": "date-time", "title": "When the rail wrote the instruction down", "type": "string" }, "queued_because": { "title": "What kind of failure the rail met when the instruction was written (`server_error (503)`, `timeout`, …) — a kind, never the request path, which names the processor's handle", "type": "string" }, "queued_by": { "title": "Who asked for it: the principal the queued request carried (its JSON), under whose name the drain records the ledger's leg — the online attempt's, not the rail's (F4, 2026-10-19)", "type": "string" }, "refund_reason": { "enum": [ "duplicate", "fraudulent", "requested_by_customer", "reservation_cancelled", "deposit_return", "service_recovery", "overcharge_correction", "no_show_policy_exception", "package_component_refund", "membership_cancellation", "chargeback_prevention", "other" ], "title": "Why a queued refund gives money back", "type": "string" }, "result_payment_id": { "title": "The payment row the outcome recorded, when it made one (a refund's leg)", "type": "string" }, "reverse_transfer": { "title": "Whether a queued refund pulls the hotel's transfer back — the online attempt's form, kept so the drained retry under the same key is the same request (F4, 2026-10-19)", "type": "boolean" }, "state": { "enum": [ "queued", "sending", "done", "refused", "abandoned", "cancelled" ], "title": "queued, sending, done, refused, abandoned or cancelled", "type": "string" }, "stay_id": { "title": "The stay a collection or a top-up is for (its object id) — the rail_instruction_for_stay edge's target", "type": "string" }, "void_reason": { "enum": [ "duplicate", "fraudulent", "requested_by_customer", "abandoned", "review_declined", "authorisation_expired", "reservation_cancelled", "guest_disputed_pre_arrival", "released_at_departure" ], "title": "Why a queued release releases the hold (the void's reason)", "type": "string" } }, "required": [ "id", "kind", "state", "property_id", "amount", "attempt_id", "attempts", "not_before", "queued_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rail_instruction:read" ] } ], "summary": "Search Rail instruction", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.rate_per_night/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA per-date price for a `(rate_plan, room_type, occupancy)` tuple. Maps directly to OTA `OTA_HotelRateAmountNotifRQ`. Rates are intentionally explicit — no derivation is implied; derived rates live on `RatePlan` itself or on a future `DerivedRate` object.", "operationId": "get_hospitality_rate_per_night", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_per_night" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "Amount per night", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Rate per night amount", "type": "object" }, "bar_anchor_amount": { "description": "BAR anchor (bar_grid rate plans)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Rate per night bar anchor amount", "type": "object" }, "business_date": { "format": "date", "title": "Business date", "type": "string" }, "id": { "title": "Rate id", "type": "string" }, "inclusive_of_tax": { "title": "Inclusive of tax", "type": "boolean" }, "occupancy": { "title": "Occupancy (adult count for this rate)", "type": "integer" } }, "required": [ "id", "business_date", "occupancy" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rate_per_night:read" ] } ], "summary": "Read Rate per night", "tags": [ "distribution" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.rate_per_night/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA per-date price for a `(rate_plan, room_type, occupancy)` tuple. Maps directly to OTA `OTA_HotelRateAmountNotifRQ`. Rates are intentionally explicit — no derivation is implied; derived rates live on `RatePlan` itself or on a future `DerivedRate` object.", "operationId": "get_hospitality_rate_per_night_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.rate_per_night" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rate_per_night:read" ] } ], "summary": "Read Rate per night as of a watermark", "tags": [ "distribution" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.rate_per_night/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA per-date price for a `(rate_plan, room_type, occupancy)` tuple. Maps directly to OTA `OTA_HotelRateAmountNotifRQ`. Rates are intentionally explicit — no derivation is implied; derived rates live on `RatePlan` itself or on a future `DerivedRate` object.", "operationId": "list_links_hospitality_rate_per_night", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rate_per_night:read" ] } ], "summary": "List links of Rate per night", "tags": [ "distribution" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.derived_rate_for_rate_per_night", "hospitality.link.rate_plan_has_rate_per_night", "hospitality.link.recommendation_applied_to_rate_per_night", "hospitality.link.room_type_has_rate_per_night" ] } } ] }, "/v1/object-types/hospitality.rate_per_night/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA per-date price for a `(rate_plan, room_type, occupancy)` tuple. Maps directly to OTA `OTA_HotelRateAmountNotifRQ`. Rates are intentionally explicit — no derivation is implied; derived rates live on `RatePlan` itself or on a future `DerivedRate` object.", "operationId": "traverse_hospitality_rate_per_night", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.derived_rate_for_rate_per_night", "hospitality.link.rate_plan_has_rate_per_night", "hospitality.link.recommendation_applied_to_rate_per_night", "hospitality.link.room_type_has_rate_per_night" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rate_per_night:read" ] } ], "summary": "Traverse from Rate per night", "tags": [ "distribution" ] } }, "/v1/object-types/hospitality.rate_per_night/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA per-date price for a `(rate_plan, room_type, occupancy)` tuple. Maps directly to OTA `OTA_HotelRateAmountNotifRQ`. Rates are intentionally explicit — no derivation is implied; derived rates live on `RatePlan` itself or on a future `DerivedRate` object.", "operationId": "search_hospitality_rate_per_night", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "occupancy" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "occupancy" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "occupancy" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "inclusive_of_tax" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "bar_anchor_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "business_date", "occupancy" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_per_night" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "Amount per night", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Rate per night amount", "type": "object" }, "bar_anchor_amount": { "description": "BAR anchor (bar_grid rate plans)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Rate per night bar anchor amount", "type": "object" }, "business_date": { "format": "date", "title": "Business date", "type": "string" }, "id": { "title": "Rate id", "type": "string" }, "inclusive_of_tax": { "title": "Inclusive of tax", "type": "boolean" }, "occupancy": { "title": "Occupancy (adult count for this rate)", "type": "integer" } }, "required": [ "id", "business_date", "occupancy" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rate_per_night:read" ] } ], "summary": "Search Rate per night", "tags": [ "distribution" ] } }, "/v1/object-types/hospitality.rate_plan/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA pricing plan attached to a property or brand. Reservations reference a rate plan to determine pricing, inclusions, and cancellation policy.", "operationId": "get_hospitality_rate_plan", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_plan" }, "properties": { "additionalProperties": false, "properties": { "cancellation_policy": { "title": "Cancellation policy", "type": "string" }, "code": { "title": "Rate plan code", "type": "string" }, "commissionable": { "title": "Whether stays on this plan earn agent commission (default true)", "type": "boolean" }, "currency": { "format": "iso-4217", "title": "Currency (ISO 4217)", "type": "string" }, "day_use": { "title": "Day-use plan (sells zero-night day slots; default false)", "type": "boolean" }, "derived_modifier_kind": { "enum": [ "percent", "absolute" ], "title": "Derived modifier kind (bar_grid only)", "type": "string" }, "description": { "title": "Description", "type": "string" }, "inclusion": { "enum": [ "room_only", "breakfast", "half_board", "full_board", "all_inclusive" ], "title": "Inclusion", "type": "string" }, "max_stay_nights": { "title": "Maximum nights", "type": "integer" }, "min_stay_nights": { "title": "Minimum nights", "type": "integer" }, "name": { "title": "Rate plan name", "type": "string" }, "pricing_strategy": { "enum": [ "bar_grid", "open_pricing", "hybrid", "static_contract" ], "title": "Pricing strategy", "type": "string" }, "yieldable": { "title": "Yieldable by revenue agent", "type": "boolean" } }, "required": [ "code", "name", "inclusion", "currency", "pricing_strategy", "yieldable" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rate_plan:read" ] } ], "summary": "Read Rate plan", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.rate_plan/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA pricing plan attached to a property or brand. Reservations reference a rate plan to determine pricing, inclusions, and cancellation policy.", "operationId": "get_hospitality_rate_plan_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.rate_plan" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rate_plan:read" ] } ], "summary": "Read Rate plan as of a watermark", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.rate_plan/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA pricing plan attached to a property or brand. Reservations reference a rate plan to determine pricing, inclusions, and cancellation policy.", "operationId": "list_links_hospitality_rate_plan", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rate_plan:read" ] } ], "summary": "List links of Rate plan", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.brand_has_rate_plan", "hospitality.link.channel_distributes_rate_plan", "hospitality.link.channel_mapping_for_rate_plan", "hospitality.link.derived_rate_for_rate_plan", "hospitality.link.property_has_rate_plan", "hospitality.link.rate_plan_has_rate_per_night", "hospitality.link.rate_plan_has_restriction", "hospitality.link.rate_plan_requires_cancellation_policy", "hospitality.link.rate_plan_requires_deposit_policy", "hospitality.link.recommendation_for_rate_plan", "hospitality.link.reservation_night_uses_rate_plan", "hospitality.link.reservation_uses_rate_plan", "hospitality.link.restriction_recommendation_for_rate_plan", "hospitality.link.stay_offer_for_rate_plan", "hospitality.link.turnaway_for_rate_plan", "hospitality.link.waitlist_entry_for_rate_plan" ] } } ] }, "/v1/object-types/hospitality.rate_plan/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA pricing plan attached to a property or brand. Reservations reference a rate plan to determine pricing, inclusions, and cancellation policy.", "operationId": "traverse_hospitality_rate_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.brand_has_rate_plan", "hospitality.link.channel_distributes_rate_plan", "hospitality.link.channel_mapping_for_rate_plan", "hospitality.link.derived_rate_for_rate_plan", "hospitality.link.property_has_rate_plan", "hospitality.link.rate_plan_has_rate_per_night", "hospitality.link.rate_plan_has_restriction", "hospitality.link.rate_plan_requires_cancellation_policy", "hospitality.link.rate_plan_requires_deposit_policy", "hospitality.link.recommendation_for_rate_plan", "hospitality.link.reservation_night_uses_rate_plan", "hospitality.link.reservation_uses_rate_plan", "hospitality.link.restriction_recommendation_for_rate_plan", "hospitality.link.stay_offer_for_rate_plan", "hospitality.link.turnaway_for_rate_plan", "hospitality.link.waitlist_entry_for_rate_plan" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rate_plan:read" ] } ], "summary": "Traverse from Rate plan", "tags": [ "booking" ] } }, "/v1/object-types/hospitality.rate_plan/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA pricing plan attached to a property or brand. Reservations reference a rate plan to determine pricing, inclusions, and cancellation policy.", "operationId": "search_hospitality_rate_plan", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "commissionable" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "inclusion" }, "type": { "const": "eq" }, "value": { "enum": [ "room_only", "breakfast", "half_board", "full_board", "all_inclusive" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_policy" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_policy" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "day_use" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "min_stay_nights" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "min_stay_nights" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "min_stay_nights" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_stay_nights" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_stay_nights" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_stay_nights" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "currency" }, "type": { "const": "eq" }, "value": { "format": "iso-4217", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "pricing_strategy" }, "type": { "const": "eq" }, "value": { "enum": [ "bar_grid", "open_pricing", "hybrid", "static_contract" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "derived_modifier_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "percent", "absolute" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "yieldable" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "description", "inclusion", "cancellation_policy", "min_stay_nights", "max_stay_nights", "pricing_strategy", "derived_modifier_kind" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_plan" }, "properties": { "additionalProperties": false, "properties": { "cancellation_policy": { "title": "Cancellation policy", "type": "string" }, "code": { "title": "Rate plan code", "type": "string" }, "commissionable": { "title": "Whether stays on this plan earn agent commission (default true)", "type": "boolean" }, "currency": { "format": "iso-4217", "title": "Currency (ISO 4217)", "type": "string" }, "day_use": { "title": "Day-use plan (sells zero-night day slots; default false)", "type": "boolean" }, "derived_modifier_kind": { "enum": [ "percent", "absolute" ], "title": "Derived modifier kind (bar_grid only)", "type": "string" }, "description": { "title": "Description", "type": "string" }, "inclusion": { "enum": [ "room_only", "breakfast", "half_board", "full_board", "all_inclusive" ], "title": "Inclusion", "type": "string" }, "max_stay_nights": { "title": "Maximum nights", "type": "integer" }, "min_stay_nights": { "title": "Minimum nights", "type": "integer" }, "name": { "title": "Rate plan name", "type": "string" }, "pricing_strategy": { "enum": [ "bar_grid", "open_pricing", "hybrid", "static_contract" ], "title": "Pricing strategy", "type": "string" }, "yieldable": { "title": "Yieldable by revenue agent", "type": "boolean" } }, "required": [ "code", "name", "inclusion", "currency", "pricing_strategy", "yieldable" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rate_plan:read" ] } ], "summary": "Search Rate plan", "tags": [ "booking" ] } }, "/v1/object-types/hospitality.rate_recommendation/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA typed rate recommendation issued by an agent against a specific (rate_plan, room_type, business_date, occupancy) tuple. Mostly-immutable post-issue: the recommendation payload (recommended_amount, lift, confidence, forecast_snapshot, factors_considered, rationale) is frozen at write time so the audit trail is the rationale at decision time, not against today's forecast. The decision_* fields mutate exactly once on the transition out of `suggested` (apply / modified_and_apply / reject / expire / supersede) — that single mutation is gated by the `decision_status_transitions` cross-link validator.", "operationId": "get_hospitality_rate_recommendation", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_recommendation" }, "properties": { "additionalProperties": false, "properties": { "applied_amount": { "description": "The amount actually applied (equals recommended_amount for plain apply; differs for modified_and_applied)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Rate recommendation applied amount", "type": "object" }, "business_date": { "format": "date", "title": "Business date the recommendation applies to", "type": "string" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Operator-facing confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Calibrated probability (0..=1) — set when the model emits one", "type": "string" }, "current_amount": { "description": "Snapshot of the target amount at issue time", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Rate recommendation current amount", "type": "object" }, "decided_at": { "format": "date-time", "title": "When the recommendation transitioned out of suggested", "type": "string" }, "decision_status": { "enum": [ "suggested", "applied", "modified_and_applied", "rejected", "expired", "superseded" ], "title": "Lifecycle state", "type": "string" }, "delta_amount": { "description": "Convenience: recommended_amount - current_amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Rate recommendation delta amount", "type": "object" }, "expires_at": { "format": "date-time", "title": "After this, decision_status moves to expired", "type": "string" }, "expires_on": { "format": "date", "title": "The house business day this lapses after. When set, the house's open business date decides expiry (not the wall clock) and expires_at is the nominal end of that day in the house's timezone", "type": "string" }, "factors_considered": { "items": { "enum": [ "pickup_pace", "booking_curve", "competitive_set", "event_calendar", "historical_pattern", "segment_mix", "channel_mix", "length_of_stay_distribution", "cancellation_rate", "no_show_rate", "package_attachment", "group_displacement", "weather", "other" ], "type": "string" }, "title": "Signals the recommendation conditioned on (the strategy that fired)", "type": "array" }, "forecast_snapshot": { "description": "Forecast snapshot frozen at issue time (per §B.2)", "properties": { "ari_score": { "format": "decimal", "type": "string" }, "as_of": { "format": "date-time", "type": "string" }, "competitive_set_adr": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "competitive_set_occupancy_pct": { "format": "decimal", "type": "string" }, "event_calendar_signal": { "type": "string" }, "forecast_kind": { "enum": [ "internal_pms", "external_rms", "external_str_compset", "hybrid", "other" ], "type": "string" }, "mpi_score": { "format": "decimal", "type": "string" }, "on_books_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "on_books_rooms": { "type": "integer" }, "pickup_last_24h": { "type": "integer" }, "pickup_last_7d": { "type": "integer" }, "rgi_score": { "format": "decimal", "type": "string" }, "transient_adr_forecast": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "transient_rooms_forecast": { "type": "integer" } }, "required": [ "forecast_kind", "as_of" ], "title": "Rate recommendation forecast snapshot", "type": "object" }, "id": { "title": "Recommendation id", "type": "string" }, "issued_at": { "format": "date-time", "title": "When the agent emitted the recommendation", "type": "string" }, "lift_pct": { "format": "decimal", "title": "Convenience: (recommended_amount / current_amount) - 1", "type": "string" }, "occupancy": { "title": "Occupancy (adult count for the target rate)", "type": "integer" }, "rationale_text": { "title": "Human-readable explanation surfaced to operators", "type": "string" }, "recommended_amount": { "description": "Proposed new amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Rate recommendation recommended amount", "type": "object" }, "rejection_reason": { "title": "Free-text reason set on reject (the gold-standard decision log pattern — see proposal §6.3)", "type": "string" }, "target_field": { "enum": [ "bar_anchor", "amount" ], "title": "Target rate_per_night field (bar_anchor for bar_grid plans; amount for open-pricing plans)", "type": "string" } }, "required": [ "id", "business_date", "occupancy", "target_field", "confidence", "factors_considered", "issued_at", "expires_at", "decision_status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rate_recommendation:read" ] } ], "summary": "Read Rate recommendation", "tags": [ "revenue_management" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.rate_recommendation/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA typed rate recommendation issued by an agent against a specific (rate_plan, room_type, business_date, occupancy) tuple. Mostly-immutable post-issue: the recommendation payload (recommended_amount, lift, confidence, forecast_snapshot, factors_considered, rationale) is frozen at write time so the audit trail is the rationale at decision time, not against today's forecast. The decision_* fields mutate exactly once on the transition out of `suggested` (apply / modified_and_apply / reject / expire / supersede) — that single mutation is gated by the `decision_status_transitions` cross-link validator.", "operationId": "get_hospitality_rate_recommendation_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.rate_recommendation" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rate_recommendation:read" ] } ], "summary": "Read Rate recommendation as of a watermark", "tags": [ "revenue_management" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.rate_recommendation/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA typed rate recommendation issued by an agent against a specific (rate_plan, room_type, business_date, occupancy) tuple. Mostly-immutable post-issue: the recommendation payload (recommended_amount, lift, confidence, forecast_snapshot, factors_considered, rationale) is frozen at write time so the audit trail is the rationale at decision time, not against today's forecast. The decision_* fields mutate exactly once on the transition out of `suggested` (apply / modified_and_apply / reject / expire / supersede) — that single mutation is gated by the `decision_status_transitions` cross-link validator.", "operationId": "list_links_hospitality_rate_recommendation", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rate_recommendation:read" ] } ], "summary": "List links of Rate recommendation", "tags": [ "revenue_management" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.recommendation_applied_to_rate_per_night", "hospitality.link.recommendation_at_property", "hospitality.link.recommendation_for_rate_plan", "hospitality.link.recommendation_for_room_type", "hospitality.link.recommendation_part_of_run", "hospitality.link.recommendation_superseded_by", "hospitality.link.workflow_run_targets_rate_recommendation" ] } } ] }, "/v1/object-types/hospitality.rate_recommendation/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA typed rate recommendation issued by an agent against a specific (rate_plan, room_type, business_date, occupancy) tuple. Mostly-immutable post-issue: the recommendation payload (recommended_amount, lift, confidence, forecast_snapshot, factors_considered, rationale) is frozen at write time so the audit trail is the rationale at decision time, not against today's forecast. The decision_* fields mutate exactly once on the transition out of `suggested` (apply / modified_and_apply / reject / expire / supersede) — that single mutation is gated by the `decision_status_transitions` cross-link validator.", "operationId": "traverse_hospitality_rate_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.recommendation_applied_to_rate_per_night", "hospitality.link.recommendation_at_property", "hospitality.link.recommendation_for_rate_plan", "hospitality.link.recommendation_for_room_type", "hospitality.link.recommendation_part_of_run", "hospitality.link.recommendation_superseded_by", "hospitality.link.workflow_run_targets_rate_recommendation" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rate_recommendation:read" ] } ], "summary": "Traverse from Rate recommendation", "tags": [ "revenue_management" ] } }, "/v1/object-types/hospitality.rate_recommendation/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA typed rate recommendation issued by an agent against a specific (rate_plan, room_type, business_date, occupancy) tuple. Mostly-immutable post-issue: the recommendation payload (recommended_amount, lift, confidence, forecast_snapshot, factors_considered, rationale) is frozen at write time so the audit trail is the rationale at decision time, not against today's forecast. The decision_* fields mutate exactly once on the transition out of `suggested` (apply / modified_and_apply / reject / expire / supersede) — that single mutation is gated by the `decision_status_transitions` cross-link validator.", "operationId": "search_hospitality_rate_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "occupancy" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "occupancy" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "occupancy" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_field" }, "type": { "const": "eq" }, "value": { "enum": [ "bar_anchor", "amount" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "current_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delta_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "lift_pct" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "lift_pct" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "lift_pct" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confidence" }, "type": { "const": "eq" }, "value": { "enum": [ "low", "medium", "high" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confidence_score" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confidence_score" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confidence_score" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "factors_considered" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "pickup_pace", "booking_curve", "competitive_set", "event_calendar", "historical_pattern", "segment_mix", "channel_mix", "length_of_stay_distribution", "cancellation_rate", "no_show_rate", "package_attachment", "group_displacement", "weather", "other" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rationale_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rationale_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "forecast_snapshot" }, "type": { "const": "eq" }, "value": { "properties": { "ari_score": { "format": "decimal", "type": "string" }, "as_of": { "format": "date-time", "type": "string" }, "competitive_set_adr": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "competitive_set_occupancy_pct": { "format": "decimal", "type": "string" }, "event_calendar_signal": { "type": "string" }, "forecast_kind": { "enum": [ "internal_pms", "external_rms", "external_str_compset", "hybrid", "other" ], "type": "string" }, "mpi_score": { "format": "decimal", "type": "string" }, "on_books_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "on_books_rooms": { "type": "integer" }, "pickup_last_24h": { "type": "integer" }, "pickup_last_7d": { "type": "integer" }, "rgi_score": { "format": "decimal", "type": "string" }, "transient_adr_forecast": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "transient_rooms_forecast": { "type": "integer" } }, "required": [ "forecast_kind", "as_of" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_on" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_on" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_on" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decision_status" }, "type": { "const": "eq" }, "value": { "enum": [ "suggested", "applied", "modified_and_applied", "rejected", "expired", "superseded" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejection_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejection_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "business_date", "occupancy", "target_field", "lift_pct", "confidence", "confidence_score", "rationale_text", "issued_at", "expires_at", "expires_on", "decision_status", "decided_at", "rejection_reason" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_recommendation" }, "properties": { "additionalProperties": false, "properties": { "applied_amount": { "description": "The amount actually applied (equals recommended_amount for plain apply; differs for modified_and_applied)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Rate recommendation applied amount", "type": "object" }, "business_date": { "format": "date", "title": "Business date the recommendation applies to", "type": "string" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Operator-facing confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Calibrated probability (0..=1) — set when the model emits one", "type": "string" }, "current_amount": { "description": "Snapshot of the target amount at issue time", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Rate recommendation current amount", "type": "object" }, "decided_at": { "format": "date-time", "title": "When the recommendation transitioned out of suggested", "type": "string" }, "decision_status": { "enum": [ "suggested", "applied", "modified_and_applied", "rejected", "expired", "superseded" ], "title": "Lifecycle state", "type": "string" }, "delta_amount": { "description": "Convenience: recommended_amount - current_amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Rate recommendation delta amount", "type": "object" }, "expires_at": { "format": "date-time", "title": "After this, decision_status moves to expired", "type": "string" }, "expires_on": { "format": "date", "title": "The house business day this lapses after. When set, the house's open business date decides expiry (not the wall clock) and expires_at is the nominal end of that day in the house's timezone", "type": "string" }, "factors_considered": { "items": { "enum": [ "pickup_pace", "booking_curve", "competitive_set", "event_calendar", "historical_pattern", "segment_mix", "channel_mix", "length_of_stay_distribution", "cancellation_rate", "no_show_rate", "package_attachment", "group_displacement", "weather", "other" ], "type": "string" }, "title": "Signals the recommendation conditioned on (the strategy that fired)", "type": "array" }, "forecast_snapshot": { "description": "Forecast snapshot frozen at issue time (per §B.2)", "properties": { "ari_score": { "format": "decimal", "type": "string" }, "as_of": { "format": "date-time", "type": "string" }, "competitive_set_adr": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "competitive_set_occupancy_pct": { "format": "decimal", "type": "string" }, "event_calendar_signal": { "type": "string" }, "forecast_kind": { "enum": [ "internal_pms", "external_rms", "external_str_compset", "hybrid", "other" ], "type": "string" }, "mpi_score": { "format": "decimal", "type": "string" }, "on_books_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "on_books_rooms": { "type": "integer" }, "pickup_last_24h": { "type": "integer" }, "pickup_last_7d": { "type": "integer" }, "rgi_score": { "format": "decimal", "type": "string" }, "transient_adr_forecast": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "transient_rooms_forecast": { "type": "integer" } }, "required": [ "forecast_kind", "as_of" ], "title": "Rate recommendation forecast snapshot", "type": "object" }, "id": { "title": "Recommendation id", "type": "string" }, "issued_at": { "format": "date-time", "title": "When the agent emitted the recommendation", "type": "string" }, "lift_pct": { "format": "decimal", "title": "Convenience: (recommended_amount / current_amount) - 1", "type": "string" }, "occupancy": { "title": "Occupancy (adult count for the target rate)", "type": "integer" }, "rationale_text": { "title": "Human-readable explanation surfaced to operators", "type": "string" }, "recommended_amount": { "description": "Proposed new amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Rate recommendation recommended amount", "type": "object" }, "rejection_reason": { "title": "Free-text reason set on reject (the gold-standard decision log pattern — see proposal §6.3)", "type": "string" }, "target_field": { "enum": [ "bar_anchor", "amount" ], "title": "Target rate_per_night field (bar_anchor for bar_grid plans; amount for open-pricing plans)", "type": "string" } }, "required": [ "id", "business_date", "occupancy", "target_field", "confidence", "factors_considered", "issued_at", "expires_at", "decision_status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rate_recommendation:read" ] } ], "summary": "Search Rate recommendation", "tags": [ "revenue_management" ] } }, "/v1/object-types/hospitality.rate_recommendation_run/objects/{id}": { "get": { "description": "Read an existing instance.\n\nBatched parent of one cadence's worth of recommendations — rate moves and sell restrictions alike — issued by an agent against a property. Append-only, immutable post-finalisation per §B.2 (matching `night_audit_run` and `channel_mix_snapshot` semantics). The four denormalised counters (`recommendations_count`, `applied_count`, `rejected_count`, `expired_count`) are §B.1 projections refreshed by the lifecycle actions; `recommendations_count_computed_at` is the refresh pair.", "operationId": "get_hospitality_rate_recommendation_run", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_recommendation_run" }, "properties": { "additionalProperties": false, "properties": { "agent_model": { "title": "Model variant if the vendor exposes it", "type": "string" }, "agent_vendor": { "title": "Agent vendor (denormalised from Principal::Agent.vendor)", "type": "string" }, "agent_version": { "title": "Agent version (denormalised from Principal::Agent.version)", "type": "string" }, "applied_count": { "title": "Count of recommendations applied (denormalised; §B.1)", "type": "integer" }, "cadence": { "enum": [ "nightly", "intraday", "hourly", "event_triggered", "manual" ], "title": "Cadence", "type": "string" }, "expired_count": { "title": "Count of recommendations expired (denormalised; §B.1)", "type": "integer" }, "failure_reason": { "title": "Set on status = failed", "type": "string" }, "finished_at": { "format": "date-time", "title": "When the run finalised — set on completed / failed", "type": "string" }, "id": { "title": "Run id", "type": "string" }, "recommendations_count": { "title": "Count of recommendations issued in this run (denormalised; §B.1)", "type": "integer" }, "recommendations_count_computed_at": { "format": "date-time", "title": "Refresh pair for the four counters (§B.1 discipline)", "type": "string" }, "rejected_count": { "title": "Count of recommendations rejected (denormalised; §B.1)", "type": "integer" }, "started_at": { "format": "date-time", "title": "When the run opened", "type": "string" }, "status": { "enum": [ "in_progress", "completed", "failed" ], "title": "Status", "type": "string" }, "target_horizon_days": { "title": "Forecast horizon the run looked over", "type": "integer" } }, "required": [ "id", "started_at", "status", "cadence", "agent_vendor", "agent_version", "target_horizon_days" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rate_recommendation_run:read" ] } ], "summary": "Read Rate recommendation run", "tags": [ "revenue_management" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.rate_recommendation_run/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nBatched parent of one cadence's worth of recommendations — rate moves and sell restrictions alike — issued by an agent against a property. Append-only, immutable post-finalisation per §B.2 (matching `night_audit_run` and `channel_mix_snapshot` semantics). The four denormalised counters (`recommendations_count`, `applied_count`, `rejected_count`, `expired_count`) are §B.1 projections refreshed by the lifecycle actions; `recommendations_count_computed_at` is the refresh pair.", "operationId": "get_hospitality_rate_recommendation_run_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.rate_recommendation_run" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rate_recommendation_run:read" ] } ], "summary": "Read Rate recommendation run as of a watermark", "tags": [ "revenue_management" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.rate_recommendation_run/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nBatched parent of one cadence's worth of recommendations — rate moves and sell restrictions alike — issued by an agent against a property. Append-only, immutable post-finalisation per §B.2 (matching `night_audit_run` and `channel_mix_snapshot` semantics). The four denormalised counters (`recommendations_count`, `applied_count`, `rejected_count`, `expired_count`) are §B.1 projections refreshed by the lifecycle actions; `recommendations_count_computed_at` is the refresh pair.", "operationId": "list_links_hospitality_rate_recommendation_run", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rate_recommendation_run:read" ] } ], "summary": "List links of Rate recommendation run", "tags": [ "revenue_management" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.recommendation_part_of_run", "hospitality.link.restriction_recommendation_part_of_run", "hospitality.link.run_for_property", "hospitality.link.sell_limit_recommendation_part_of_run" ] } } ] }, "/v1/object-types/hospitality.rate_recommendation_run/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nBatched parent of one cadence's worth of recommendations — rate moves and sell restrictions alike — issued by an agent against a property. Append-only, immutable post-finalisation per §B.2 (matching `night_audit_run` and `channel_mix_snapshot` semantics). The four denormalised counters (`recommendations_count`, `applied_count`, `rejected_count`, `expired_count`) are §B.1 projections refreshed by the lifecycle actions; `recommendations_count_computed_at` is the refresh pair.", "operationId": "traverse_hospitality_rate_recommendation_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.recommendation_part_of_run", "hospitality.link.restriction_recommendation_part_of_run", "hospitality.link.run_for_property", "hospitality.link.sell_limit_recommendation_part_of_run" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rate_recommendation_run:read" ] } ], "summary": "Traverse from Rate recommendation run", "tags": [ "revenue_management" ] } }, "/v1/object-types/hospitality.rate_recommendation_run/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nBatched parent of one cadence's worth of recommendations — rate moves and sell restrictions alike — issued by an agent against a property. Append-only, immutable post-finalisation per §B.2 (matching `night_audit_run` and `channel_mix_snapshot` semantics). The four denormalised counters (`recommendations_count`, `applied_count`, `rejected_count`, `expired_count`) are §B.1 projections refreshed by the lifecycle actions; `recommendations_count_computed_at` is the refresh pair.", "operationId": "search_hospitality_rate_recommendation_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "finished_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "finished_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "finished_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "in_progress", "completed", "failed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cadence" }, "type": { "const": "eq" }, "value": { "enum": [ "nightly", "intraday", "hourly", "event_triggered", "manual" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_vendor" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_vendor" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_vendor" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_vendor" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_version" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_version" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_version" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_version" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_model" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_model" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_model" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_model" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_horizon_days" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_horizon_days" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_horizon_days" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommendations_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommendations_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommendations_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejected_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejected_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejected_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expired_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expired_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expired_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommendations_count_computed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommendations_count_computed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommendations_count_computed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "failure_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "failure_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "started_at", "finished_at", "status", "cadence", "agent_vendor", "agent_version", "agent_model", "target_horizon_days", "recommendations_count", "applied_count", "rejected_count", "expired_count", "recommendations_count_computed_at", "failure_reason" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_recommendation_run" }, "properties": { "additionalProperties": false, "properties": { "agent_model": { "title": "Model variant if the vendor exposes it", "type": "string" }, "agent_vendor": { "title": "Agent vendor (denormalised from Principal::Agent.vendor)", "type": "string" }, "agent_version": { "title": "Agent version (denormalised from Principal::Agent.version)", "type": "string" }, "applied_count": { "title": "Count of recommendations applied (denormalised; §B.1)", "type": "integer" }, "cadence": { "enum": [ "nightly", "intraday", "hourly", "event_triggered", "manual" ], "title": "Cadence", "type": "string" }, "expired_count": { "title": "Count of recommendations expired (denormalised; §B.1)", "type": "integer" }, "failure_reason": { "title": "Set on status = failed", "type": "string" }, "finished_at": { "format": "date-time", "title": "When the run finalised — set on completed / failed", "type": "string" }, "id": { "title": "Run id", "type": "string" }, "recommendations_count": { "title": "Count of recommendations issued in this run (denormalised; §B.1)", "type": "integer" }, "recommendations_count_computed_at": { "format": "date-time", "title": "Refresh pair for the four counters (§B.1 discipline)", "type": "string" }, "rejected_count": { "title": "Count of recommendations rejected (denormalised; §B.1)", "type": "integer" }, "started_at": { "format": "date-time", "title": "When the run opened", "type": "string" }, "status": { "enum": [ "in_progress", "completed", "failed" ], "title": "Status", "type": "string" }, "target_horizon_days": { "title": "Forecast horizon the run looked over", "type": "integer" } }, "required": [ "id", "started_at", "status", "cadence", "agent_vendor", "agent_version", "target_horizon_days" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rate_recommendation_run:read" ] } ], "summary": "Search Rate recommendation run", "tags": [ "revenue_management" ] } }, "/v1/object-types/hospitality.rate_restriction/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA date-range constraint on a rate plan / room type pair: closed-to-arrival (CTA), closed-to-departure (CTD), minimum/maximum length-of-stay (MinLOS/MaxLOS), and a hard `closed` stop-sell. Maps to OTA `OTA_HotelAvailNotifRQ` restrictions. Multiple restrictions can apply to the same date — the platform composes them as the conjunction. The validator on this type enforces `start_date <= end_date` and `min_length_of_stay <= max_length_of_stay` on every write.", "operationId": "get_hospitality_rate_restriction", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_restriction" }, "properties": { "additionalProperties": false, "properties": { "closed": { "title": "Closed (stop-sell)", "type": "boolean" }, "closed_to_arrival": { "title": "Closed to arrival", "type": "boolean" }, "closed_to_departure": { "title": "Closed to departure", "type": "boolean" }, "end_date": { "format": "date", "title": "End date (inclusive)", "type": "string" }, "external_ref": { "title": "Replay key for an authoring source (unique per tenant while present)", "type": "string" }, "id": { "title": "Restriction id", "type": "string" }, "lifted_at": { "format": "date-time", "title": "Business time the restriction was lifted; a lifted row constrains nothing and is kept as history", "type": "string" }, "max_length_of_stay": { "title": "Maximum length of stay (nights)", "type": "integer" }, "min_length_of_stay": { "title": "Minimum length of stay (nights)", "type": "integer" }, "posted_at": { "format": "date-time", "title": "Business time the restriction was posted (defaults to record time)", "type": "string" }, "start_date": { "format": "date", "title": "Start date", "type": "string" } }, "required": [ "id", "start_date", "end_date", "closed", "closed_to_arrival", "closed_to_departure" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rate_restriction:read" ] } ], "summary": "Read Rate restriction", "tags": [ "distribution" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.rate_restriction/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA date-range constraint on a rate plan / room type pair: closed-to-arrival (CTA), closed-to-departure (CTD), minimum/maximum length-of-stay (MinLOS/MaxLOS), and a hard `closed` stop-sell. Maps to OTA `OTA_HotelAvailNotifRQ` restrictions. Multiple restrictions can apply to the same date — the platform composes them as the conjunction. The validator on this type enforces `start_date <= end_date` and `min_length_of_stay <= max_length_of_stay` on every write.", "operationId": "get_hospitality_rate_restriction_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.rate_restriction" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rate_restriction:read" ] } ], "summary": "Read Rate restriction as of a watermark", "tags": [ "distribution" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.rate_restriction/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA date-range constraint on a rate plan / room type pair: closed-to-arrival (CTA), closed-to-departure (CTD), minimum/maximum length-of-stay (MinLOS/MaxLOS), and a hard `closed` stop-sell. Maps to OTA `OTA_HotelAvailNotifRQ` restrictions. Multiple restrictions can apply to the same date — the platform composes them as the conjunction. The validator on this type enforces `start_date <= end_date` and `min_length_of_stay <= max_length_of_stay` on every write.", "operationId": "list_links_hospitality_rate_restriction", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rate_restriction:read" ] } ], "summary": "List links of Rate restriction", "tags": [ "distribution" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.rate_plan_has_restriction", "hospitality.link.restriction_recommendation_applied_to_rate_restriction", "hospitality.link.restriction_recommendation_lifted_rate_restriction", "hospitality.link.room_type_has_restriction" ] } } ] }, "/v1/object-types/hospitality.rate_restriction/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA date-range constraint on a rate plan / room type pair: closed-to-arrival (CTA), closed-to-departure (CTD), minimum/maximum length-of-stay (MinLOS/MaxLOS), and a hard `closed` stop-sell. Maps to OTA `OTA_HotelAvailNotifRQ` restrictions. Multiple restrictions can apply to the same date — the platform composes them as the conjunction. The validator on this type enforces `start_date <= end_date` and `min_length_of_stay <= max_length_of_stay` on every write.", "operationId": "traverse_hospitality_rate_restriction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.rate_plan_has_restriction", "hospitality.link.restriction_recommendation_applied_to_rate_restriction", "hospitality.link.restriction_recommendation_lifted_rate_restriction", "hospitality.link.room_type_has_restriction" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rate_restriction:read" ] } ], "summary": "Traverse from Rate restriction", "tags": [ "distribution" ] } }, "/v1/object-types/hospitality.rate_restriction/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA date-range constraint on a rate plan / room type pair: closed-to-arrival (CTA), closed-to-departure (CTD), minimum/maximum length-of-stay (MinLOS/MaxLOS), and a hard `closed` stop-sell. Maps to OTA `OTA_HotelAvailNotifRQ` restrictions. Multiple restrictions can apply to the same date — the platform composes them as the conjunction. The validator on this type enforces `start_date <= end_date` and `min_length_of_stay <= max_length_of_stay` on every write.", "operationId": "search_hospitality_rate_restriction", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "start_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "start_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "start_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "end_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "end_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "end_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed_to_arrival" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed_to_departure" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "min_length_of_stay" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "min_length_of_stay" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "min_length_of_stay" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_length_of_stay" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_length_of_stay" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_length_of_stay" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "posted_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "posted_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "posted_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "lifted_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "lifted_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "lifted_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "start_date", "end_date", "min_length_of_stay", "max_length_of_stay", "posted_at", "lifted_at", "external_ref" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.rate_restriction" }, "properties": { "additionalProperties": false, "properties": { "closed": { "title": "Closed (stop-sell)", "type": "boolean" }, "closed_to_arrival": { "title": "Closed to arrival", "type": "boolean" }, "closed_to_departure": { "title": "Closed to departure", "type": "boolean" }, "end_date": { "format": "date", "title": "End date (inclusive)", "type": "string" }, "external_ref": { "title": "Replay key for an authoring source (unique per tenant while present)", "type": "string" }, "id": { "title": "Restriction id", "type": "string" }, "lifted_at": { "format": "date-time", "title": "Business time the restriction was lifted; a lifted row constrains nothing and is kept as history", "type": "string" }, "max_length_of_stay": { "title": "Maximum length of stay (nights)", "type": "integer" }, "min_length_of_stay": { "title": "Minimum length of stay (nights)", "type": "integer" }, "posted_at": { "format": "date-time", "title": "Business time the restriction was posted (defaults to record time)", "type": "string" }, "start_date": { "format": "date", "title": "Start date", "type": "string" } }, "required": [ "id", "start_date", "end_date", "closed", "closed_to_arrival", "closed_to_departure" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.rate_restriction:read" ] } ], "summary": "Search Rate restriction", "tags": [ "distribution" ] } }, "/v1/object-types/hospitality.recipe/objects/{id}": { "get": { "description": "Read an existing instance.\n\nProduction-side spec for a saleable item. 1:1 with `service_item` via `recipe_for_service_item`; composes other recipes via `recipe_uses_sub_recipe` (a clarified milk-wash referenced by multiple cocktails); references typed `ingredient` rows for pour-cost rollup. Allergens flow up from ingredient flags; the recipe `allergens` array is the producer- side rolled disclosure.", "operationId": "get_hospitality_recipe", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.recipe" }, "properties": { "additionalProperties": false, "properties": { "allergens": { "items": { "enum": [ "gluten", "crustaceans", "eggs", "fish", "peanuts", "soybeans", "milk", "nuts", "celery", "mustard", "sesame", "sulphites", "lupin", "molluscs" ], "type": "string" }, "title": "Allergens (rollup; EU 14 list)", "type": "array" }, "build_duration_seconds": { "title": "Build duration (seconds)", "type": "integer" }, "build_method": { "enum": [ "stir", "shake", "build", "swizzle", "throw", "blend", "layer", "carbonate", "sous_vide", "milk_wash", "clarify", "bake", "grill", "saute", "sear", "braise", "poach", "other" ], "title": "Build method", "type": "string" }, "dietary_classification": { "items": { "enum": [ "vegan", "vegetarian", "pescatarian", "halal", "kosher", "low_fodmap", "gluten_free", "dairy_free", "sugar_free", "keto", "paleo", "raw", "other" ], "type": "string" }, "title": "Dietary classification (lifestyle, not regulatory)", "type": "array" }, "dilution_percent": { "format": "decimal", "title": "Dilution percent (drink_*)", "type": "string" }, "garnishes": { "items": { "type": "string" }, "title": "Garnishes", "type": "array" }, "glass_specifier": { "title": "Glass specifier (brand/size override)", "type": "string" }, "glass_type": { "enum": [ "nick_nora", "coupe", "rocks", "highball", "collins", "flute", "wine_red", "wine_white", "mug", "snifter", "tiki", "other" ], "title": "Glass type (drink_*)", "type": "string" }, "ice_type": { "enum": [ "crushed", "cube", "big_rock", "sphere", "shaved", "none", "other" ], "title": "Ice type (drink_*)", "type": "string" }, "id": { "title": "Recipe id", "type": "string" }, "ingredients": { "description": "Ingredients (typed)", "items": { "properties": { "allergen_flags": { "items": { "enum": [ "gluten", "crustaceans", "eggs", "fish", "peanuts", "soybeans", "milk", "nuts", "celery", "mustard", "sesame", "sulphites", "lupin", "molluscs" ], "type": "string" }, "type": "array" }, "garnish_role": { "type": "string" }, "ingredient_ref": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.ingredient" }, "name": { "type": "string" }, "notes": { "type": "string" }, "quantity": { "format": "decimal", "type": "string" }, "sub_recipe_ref": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.recipe" }, "unit": { "enum": [ "ml", "cl", "oz", "g", "kg", "each", "dash", "drop", "rim", "float", "scoop", "other" ], "type": "string" } }, "required": [ "quantity", "unit" ], "type": "object" }, "title": "Recipe ingredients", "type": "array" }, "method_steps": { "items": { "type": "string" }, "title": "Method steps (ordered prep instructions)", "type": "array" }, "pour_cost": { "description": "Pour cost (projection)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Recipe pour cost", "type": "object" }, "pour_cost_computed_at": { "format": "date-time", "title": "Pour cost refresh timestamp", "type": "string" }, "pre_batch": { "title": "Pre-batched", "type": "boolean" }, "recipe_kind": { "enum": [ "drink_cocktail", "drink_coffee", "drink_tea", "drink_wine_pour", "dish_main", "dish_side", "dish_dessert", "dish_amuse", "spa_treatment_protocol", "other" ], "title": "Recipe kind", "type": "string" }, "sell_price": { "description": "Sell price (cache from service_item)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Recipe sell price", "type": "object" }, "serves_per_batch": { "title": "Serves per batch", "type": "integer" }, "shelf_life_hours": { "title": "Shelf life (hours)", "type": "integer" }, "shelf_life_storage": { "enum": [ "ambient", "refrigerated", "frozen", "controlled_atmosphere", "other" ], "title": "Shelf life storage", "type": "string" } }, "required": [ "id", "recipe_kind", "serves_per_batch", "pre_batch", "ingredients" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.recipe:read" ] } ], "summary": "Read Recipe", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.recipe/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nProduction-side spec for a saleable item. 1:1 with `service_item` via `recipe_for_service_item`; composes other recipes via `recipe_uses_sub_recipe` (a clarified milk-wash referenced by multiple cocktails); references typed `ingredient` rows for pour-cost rollup. Allergens flow up from ingredient flags; the recipe `allergens` array is the producer- side rolled disclosure.", "operationId": "get_hospitality_recipe_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.recipe" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.recipe:read" ] } ], "summary": "Read Recipe as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.recipe/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nProduction-side spec for a saleable item. 1:1 with `service_item` via `recipe_for_service_item`; composes other recipes via `recipe_uses_sub_recipe` (a clarified milk-wash referenced by multiple cocktails); references typed `ingredient` rows for pour-cost rollup. Allergens flow up from ingredient flags; the recipe `allergens` array is the producer- side rolled disclosure.", "operationId": "list_links_hospitality_recipe", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.recipe:read" ] } ], "summary": "List links of Recipe", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.menu_item_uses_recipe", "hospitality.link.recipe_at_brand", "hospitality.link.recipe_at_property", "hospitality.link.recipe_for_service_item", "hospitality.link.recipe_uses_ingredient", "hospitality.link.recipe_uses_sub_recipe" ] } } ] }, "/v1/object-types/hospitality.recipe/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nProduction-side spec for a saleable item. 1:1 with `service_item` via `recipe_for_service_item`; composes other recipes via `recipe_uses_sub_recipe` (a clarified milk-wash referenced by multiple cocktails); references typed `ingredient` rows for pour-cost rollup. Allergens flow up from ingredient flags; the recipe `allergens` array is the producer- side rolled disclosure.", "operationId": "traverse_hospitality_recipe", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.menu_item_uses_recipe", "hospitality.link.recipe_at_brand", "hospitality.link.recipe_at_property", "hospitality.link.recipe_for_service_item", "hospitality.link.recipe_uses_ingredient", "hospitality.link.recipe_uses_sub_recipe" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.recipe:read" ] } ], "summary": "Traverse from Recipe", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.recipe/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nProduction-side spec for a saleable item. 1:1 with `service_item` via `recipe_for_service_item`; composes other recipes via `recipe_uses_sub_recipe` (a clarified milk-wash referenced by multiple cocktails); references typed `ingredient` rows for pour-cost rollup. Allergens flow up from ingredient flags; the recipe `allergens` array is the producer- side rolled disclosure.", "operationId": "search_hospitality_recipe", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recipe_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "drink_cocktail", "drink_coffee", "drink_tea", "drink_wine_pour", "dish_main", "dish_side", "dish_dessert", "dish_amuse", "spa_treatment_protocol", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "serves_per_batch" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "serves_per_batch" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "serves_per_batch" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "pre_batch" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ingredients" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "allergen_flags": { "items": { "enum": [ "gluten", "crustaceans", "eggs", "fish", "peanuts", "soybeans", "milk", "nuts", "celery", "mustard", "sesame", "sulphites", "lupin", "molluscs" ], "type": "string" }, "type": "array" }, "garnish_role": { "type": "string" }, "ingredient_ref": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.ingredient" }, "name": { "type": "string" }, "notes": { "type": "string" }, "quantity": { "format": "decimal", "type": "string" }, "sub_recipe_ref": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.recipe" }, "unit": { "enum": [ "ml", "cl", "oz", "g", "kg", "each", "dash", "drop", "rim", "float", "scoop", "other" ], "type": "string" } }, "required": [ "quantity", "unit" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "build_method" }, "type": { "const": "eq" }, "value": { "enum": [ "stir", "shake", "build", "swizzle", "throw", "blend", "layer", "carbonate", "sous_vide", "milk_wash", "clarify", "bake", "grill", "saute", "sear", "braise", "poach", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "build_duration_seconds" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "build_duration_seconds" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "build_duration_seconds" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dilution_percent" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dilution_percent" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dilution_percent" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "glass_type" }, "type": { "const": "eq" }, "value": { "enum": [ "nick_nora", "coupe", "rocks", "highball", "collins", "flute", "wine_red", "wine_white", "mug", "snifter", "tiki", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "glass_specifier" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "glass_specifier" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "glass_specifier" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "glass_specifier" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ice_type" }, "type": { "const": "eq" }, "value": { "enum": [ "crushed", "cube", "big_rock", "sphere", "shaved", "none", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "garnishes" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "shelf_life_hours" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "shelf_life_hours" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "shelf_life_hours" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "shelf_life_storage" }, "type": { "const": "eq" }, "value": { "enum": [ "ambient", "refrigerated", "frozen", "controlled_atmosphere", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "pour_cost" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "pour_cost_computed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "pour_cost_computed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "pour_cost_computed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sell_price" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "allergens" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "gluten", "crustaceans", "eggs", "fish", "peanuts", "soybeans", "milk", "nuts", "celery", "mustard", "sesame", "sulphites", "lupin", "molluscs" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "dietary_classification" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "vegan", "vegetarian", "pescatarian", "halal", "kosher", "low_fodmap", "gluten_free", "dairy_free", "sugar_free", "keto", "paleo", "raw", "other" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "method_steps" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "recipe_kind", "serves_per_batch", "build_method", "build_duration_seconds", "dilution_percent", "glass_type", "glass_specifier", "ice_type", "shelf_life_hours", "shelf_life_storage", "pour_cost_computed_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.recipe" }, "properties": { "additionalProperties": false, "properties": { "allergens": { "items": { "enum": [ "gluten", "crustaceans", "eggs", "fish", "peanuts", "soybeans", "milk", "nuts", "celery", "mustard", "sesame", "sulphites", "lupin", "molluscs" ], "type": "string" }, "title": "Allergens (rollup; EU 14 list)", "type": "array" }, "build_duration_seconds": { "title": "Build duration (seconds)", "type": "integer" }, "build_method": { "enum": [ "stir", "shake", "build", "swizzle", "throw", "blend", "layer", "carbonate", "sous_vide", "milk_wash", "clarify", "bake", "grill", "saute", "sear", "braise", "poach", "other" ], "title": "Build method", "type": "string" }, "dietary_classification": { "items": { "enum": [ "vegan", "vegetarian", "pescatarian", "halal", "kosher", "low_fodmap", "gluten_free", "dairy_free", "sugar_free", "keto", "paleo", "raw", "other" ], "type": "string" }, "title": "Dietary classification (lifestyle, not regulatory)", "type": "array" }, "dilution_percent": { "format": "decimal", "title": "Dilution percent (drink_*)", "type": "string" }, "garnishes": { "items": { "type": "string" }, "title": "Garnishes", "type": "array" }, "glass_specifier": { "title": "Glass specifier (brand/size override)", "type": "string" }, "glass_type": { "enum": [ "nick_nora", "coupe", "rocks", "highball", "collins", "flute", "wine_red", "wine_white", "mug", "snifter", "tiki", "other" ], "title": "Glass type (drink_*)", "type": "string" }, "ice_type": { "enum": [ "crushed", "cube", "big_rock", "sphere", "shaved", "none", "other" ], "title": "Ice type (drink_*)", "type": "string" }, "id": { "title": "Recipe id", "type": "string" }, "ingredients": { "description": "Ingredients (typed)", "items": { "properties": { "allergen_flags": { "items": { "enum": [ "gluten", "crustaceans", "eggs", "fish", "peanuts", "soybeans", "milk", "nuts", "celery", "mustard", "sesame", "sulphites", "lupin", "molluscs" ], "type": "string" }, "type": "array" }, "garnish_role": { "type": "string" }, "ingredient_ref": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.ingredient" }, "name": { "type": "string" }, "notes": { "type": "string" }, "quantity": { "format": "decimal", "type": "string" }, "sub_recipe_ref": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.recipe" }, "unit": { "enum": [ "ml", "cl", "oz", "g", "kg", "each", "dash", "drop", "rim", "float", "scoop", "other" ], "type": "string" } }, "required": [ "quantity", "unit" ], "type": "object" }, "title": "Recipe ingredients", "type": "array" }, "method_steps": { "items": { "type": "string" }, "title": "Method steps (ordered prep instructions)", "type": "array" }, "pour_cost": { "description": "Pour cost (projection)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Recipe pour cost", "type": "object" }, "pour_cost_computed_at": { "format": "date-time", "title": "Pour cost refresh timestamp", "type": "string" }, "pre_batch": { "title": "Pre-batched", "type": "boolean" }, "recipe_kind": { "enum": [ "drink_cocktail", "drink_coffee", "drink_tea", "drink_wine_pour", "dish_main", "dish_side", "dish_dessert", "dish_amuse", "spa_treatment_protocol", "other" ], "title": "Recipe kind", "type": "string" }, "sell_price": { "description": "Sell price (cache from service_item)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Recipe sell price", "type": "object" }, "serves_per_batch": { "title": "Serves per batch", "type": "integer" }, "shelf_life_hours": { "title": "Shelf life (hours)", "type": "integer" }, "shelf_life_storage": { "enum": [ "ambient", "refrigerated", "frozen", "controlled_atmosphere", "other" ], "title": "Shelf life storage", "type": "string" } }, "required": [ "id", "recipe_kind", "serves_per_batch", "pre_batch", "ingredients" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.recipe:read" ] } ], "summary": "Search Recipe", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.reciprocity_agreement/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe org-to-org primitive. Yacht-club reciprocity, Soho House Every House, partner-tier drop-ins, LHW Leaders Club at SLH-Hilton-partnership properties. Distinct from `membership_tier` because the agreement is between organisations (with cost structure and access scope) and individual member access flows through the agreement, not through a duplicated tier on the partner organisation's side.", "operationId": "get_hospitality_reciprocity_agreement", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reciprocity_agreement" }, "properties": { "additionalProperties": false, "properties": { "access_scope": { "enum": [ "full_access", "shared_with_restrictions", "drop_in_only", "network_member" ], "title": "Access scope (full / shared / drop-in / network)", "type": "string" }, "agreement_kind": { "enum": [ "bilateral", "unilateral_inbound", "unilateral_outbound", "network_membership" ], "title": "Agreement kind (bilateral / unilateral / network)", "type": "string" }, "agreement_terms_text": { "title": "Agreement-terms snapshot at signing (design-spec §B.2)", "type": "string" }, "code": { "title": "Agreement code", "type": "string" }, "cost_structure": { "enum": [ "free", "member_pays_drop_in", "member_pays_full", "host_pays_per_visit", "reciprocal_credits" ], "title": "Cost structure (who pays and how)", "type": "string" }, "description": { "title": "Description", "type": "string" }, "effective_from": { "format": "date", "title": "Effective from", "type": "string" }, "effective_to": { "format": "date", "title": "Effective to (null when ongoing)", "type": "string" }, "is_active": { "title": "Currently active", "type": "boolean" }, "monthly_visit_cap": { "title": "Monthly visit cap (capped reciprocity)", "type": "integer" }, "name": { "title": "Agreement name", "type": "string" }, "per_visit_fee_amount": { "description": "Per-visit fee (required when cost_structure ∈ {member_pays_drop_in, host_pays_per_visit})", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Reciprocity agreement per visit fee amount", "type": "object" }, "per_visit_fee_currency": { "format": "iso-4217", "title": "Per-visit fee currency (ISO 4217)", "type": "string" } }, "required": [ "code", "name", "agreement_kind", "access_scope", "cost_structure", "effective_from", "is_active" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.reciprocity_agreement:read" ] } ], "summary": "Read Reciprocity agreement", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.reciprocity_agreement/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe org-to-org primitive. Yacht-club reciprocity, Soho House Every House, partner-tier drop-ins, LHW Leaders Club at SLH-Hilton-partnership properties. Distinct from `membership_tier` because the agreement is between organisations (with cost structure and access scope) and individual member access flows through the agreement, not through a duplicated tier on the partner organisation's side.", "operationId": "get_hospitality_reciprocity_agreement_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.reciprocity_agreement" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.reciprocity_agreement:read" ] } ], "summary": "Read Reciprocity agreement as of a watermark", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.reciprocity_agreement/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe org-to-org primitive. Yacht-club reciprocity, Soho House Every House, partner-tier drop-ins, LHW Leaders Club at SLH-Hilton-partnership properties. Distinct from `membership_tier` because the agreement is between organisations (with cost structure and access scope) and individual member access flows through the agreement, not through a duplicated tier on the partner organisation's side.", "operationId": "list_links_hospitality_reciprocity_agreement", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.reciprocity_agreement:read" ] } ], "summary": "List links of Reciprocity agreement", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.reciprocity_agreement_between_orgs" ] } } ] }, "/v1/object-types/hospitality.reciprocity_agreement/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe org-to-org primitive. Yacht-club reciprocity, Soho House Every House, partner-tier drop-ins, LHW Leaders Club at SLH-Hilton-partnership properties. Distinct from `membership_tier` because the agreement is between organisations (with cost structure and access scope) and individual member access flows through the agreement, not through a duplicated tier on the partner organisation's side.", "operationId": "traverse_hospitality_reciprocity_agreement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.reciprocity_agreement_between_orgs" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.reciprocity_agreement:read" ] } ], "summary": "Traverse from Reciprocity agreement", "tags": [ "membership" ] } }, "/v1/object-types/hospitality.reciprocity_agreement/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe org-to-org primitive. Yacht-club reciprocity, Soho House Every House, partner-tier drop-ins, LHW Leaders Club at SLH-Hilton-partnership properties. Distinct from `membership_tier` because the agreement is between organisations (with cost structure and access scope) and individual member access flows through the agreement, not through a duplicated tier on the partner organisation's side.", "operationId": "search_hospitality_reciprocity_agreement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agreement_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "bilateral", "unilateral_inbound", "unilateral_outbound", "network_membership" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "access_scope" }, "type": { "const": "eq" }, "value": { "enum": [ "full_access", "shared_with_restrictions", "drop_in_only", "network_member" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cost_structure" }, "type": { "const": "eq" }, "value": { "enum": [ "free", "member_pays_drop_in", "member_pays_full", "host_pays_per_visit", "reciprocal_credits" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "is_active" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "per_visit_fee_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "per_visit_fee_currency" }, "type": { "const": "eq" }, "value": { "format": "iso-4217", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "monthly_visit_cap" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "monthly_visit_cap" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "monthly_visit_cap" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agreement_terms_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agreement_terms_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "agreement_kind", "access_scope", "cost_structure", "effective_from", "effective_to", "monthly_visit_cap", "description", "agreement_terms_text" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reciprocity_agreement" }, "properties": { "additionalProperties": false, "properties": { "access_scope": { "enum": [ "full_access", "shared_with_restrictions", "drop_in_only", "network_member" ], "title": "Access scope (full / shared / drop-in / network)", "type": "string" }, "agreement_kind": { "enum": [ "bilateral", "unilateral_inbound", "unilateral_outbound", "network_membership" ], "title": "Agreement kind (bilateral / unilateral / network)", "type": "string" }, "agreement_terms_text": { "title": "Agreement-terms snapshot at signing (design-spec §B.2)", "type": "string" }, "code": { "title": "Agreement code", "type": "string" }, "cost_structure": { "enum": [ "free", "member_pays_drop_in", "member_pays_full", "host_pays_per_visit", "reciprocal_credits" ], "title": "Cost structure (who pays and how)", "type": "string" }, "description": { "title": "Description", "type": "string" }, "effective_from": { "format": "date", "title": "Effective from", "type": "string" }, "effective_to": { "format": "date", "title": "Effective to (null when ongoing)", "type": "string" }, "is_active": { "title": "Currently active", "type": "boolean" }, "monthly_visit_cap": { "title": "Monthly visit cap (capped reciprocity)", "type": "integer" }, "name": { "title": "Agreement name", "type": "string" }, "per_visit_fee_amount": { "description": "Per-visit fee (required when cost_structure ∈ {member_pays_drop_in, host_pays_per_visit})", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Reciprocity agreement per visit fee amount", "type": "object" }, "per_visit_fee_currency": { "format": "iso-4217", "title": "Per-visit fee currency (ISO 4217)", "type": "string" } }, "required": [ "code", "name", "agreement_kind", "access_scope", "cost_structure", "effective_from", "is_active" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.reciprocity_agreement:read" ] } ], "summary": "Search Reciprocity agreement", "tags": [ "membership" ] } }, "/v1/object-types/hospitality.recognition_event/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA recorded recognition of a person — name acknowledged, preference anticipated, relationship remembered, gesture offered, upgrade provided, amenity provided, personal note left, birthday or anniversary marked, repeat visit acknowledged, VIP treatment initiated. Always-on across all loyalty archetypes — the program_type does not gate recognition; Aman runs recognition-only and Maybourne runs LHW + deep internal recognition independently. `delivery_visibility` types the Aman invisible-attention vs Ritz visible-attention axis: the same recognition can be delivered visibly (a hand-written welcome card on arrival) or invisibly (the temperature set to the guest's preference before they enter the room). The pair with proposal 0002's `service_recovery_event` lets the read-side projection surface the operator's recognition-vs-recovery balance.", "operationId": "get_hospitality_recognition_event", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.recognition_event" }, "properties": { "additionalProperties": false, "properties": { "comp_amount": { "description": "Comp amount when recognition includes value", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Recognition event comp amount", "type": "object" }, "comp_category": { "title": "Comp category (toolkit dictionary key)", "type": "string" }, "delivery_visibility": { "enum": [ "visible_to_guest", "invisible_to_guest" ], "title": "Delivery visibility", "type": "string" }, "happened_at": { "format": "date-time", "title": "When the recognition happened", "type": "string" }, "id": { "title": "Recognition event id", "type": "string" }, "recogniser": { "title": "Recogniser principal identifier", "type": "string" }, "recognition_action_text": { "title": "What the operator did", "type": "string" }, "recognition_kind": { "enum": [ "name_acknowledged", "preference_anticipated", "relationship_remembered", "gesture_offered", "upgrade_provided", "amenity_provided", "personal_note_left", "birthday_anniversary_marked", "repeat_visit_acknowledged", "vip_treatment_initiated", "other" ], "title": "Recognition kind", "type": "string" }, "recognition_subject_text": { "title": "What was recognised", "type": "string" }, "stay_id": { "title": "Stay context (when applicable)", "type": "string" } }, "required": [ "id", "recognition_kind", "delivery_visibility", "happened_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.recognition_event:read" ] } ], "summary": "Read Recognition event", "tags": [ "loyalty" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.recognition_event/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA recorded recognition of a person — name acknowledged, preference anticipated, relationship remembered, gesture offered, upgrade provided, amenity provided, personal note left, birthday or anniversary marked, repeat visit acknowledged, VIP treatment initiated. Always-on across all loyalty archetypes — the program_type does not gate recognition; Aman runs recognition-only and Maybourne runs LHW + deep internal recognition independently. `delivery_visibility` types the Aman invisible-attention vs Ritz visible-attention axis: the same recognition can be delivered visibly (a hand-written welcome card on arrival) or invisibly (the temperature set to the guest's preference before they enter the room). The pair with proposal 0002's `service_recovery_event` lets the read-side projection surface the operator's recognition-vs-recovery balance.", "operationId": "get_hospitality_recognition_event_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.recognition_event" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.recognition_event:read" ] } ], "summary": "Read Recognition event as of a watermark", "tags": [ "loyalty" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.recognition_event/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA recorded recognition of a person — name acknowledged, preference anticipated, relationship remembered, gesture offered, upgrade provided, amenity provided, personal note left, birthday or anniversary marked, repeat visit acknowledged, VIP treatment initiated. Always-on across all loyalty archetypes — the program_type does not gate recognition; Aman runs recognition-only and Maybourne runs LHW + deep internal recognition independently. `delivery_visibility` types the Aman invisible-attention vs Ritz visible-attention axis: the same recognition can be delivered visibly (a hand-written welcome card on arrival) or invisibly (the temperature set to the guest's preference before they enter the room). The pair with proposal 0002's `service_recovery_event` lets the read-side projection surface the operator's recognition-vs-recovery balance.", "operationId": "list_links_hospitality_recognition_event", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.recognition_event:read" ] } ], "summary": "List links of Recognition event", "tags": [ "loyalty" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.recognition_event_at_property", "hospitality.link.recognition_event_for_person", "hospitality.link.recognition_event_for_program" ] } } ] }, "/v1/object-types/hospitality.recognition_event/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA recorded recognition of a person — name acknowledged, preference anticipated, relationship remembered, gesture offered, upgrade provided, amenity provided, personal note left, birthday or anniversary marked, repeat visit acknowledged, VIP treatment initiated. Always-on across all loyalty archetypes — the program_type does not gate recognition; Aman runs recognition-only and Maybourne runs LHW + deep internal recognition independently. `delivery_visibility` types the Aman invisible-attention vs Ritz visible-attention axis: the same recognition can be delivered visibly (a hand-written welcome card on arrival) or invisibly (the temperature set to the guest's preference before they enter the room). The pair with proposal 0002's `service_recovery_event` lets the read-side projection surface the operator's recognition-vs-recovery balance.", "operationId": "traverse_hospitality_recognition_event", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.recognition_event_at_property", "hospitality.link.recognition_event_for_person", "hospitality.link.recognition_event_for_program" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.recognition_event:read" ] } ], "summary": "Traverse from Recognition event", "tags": [ "loyalty" ] } }, "/v1/object-types/hospitality.recognition_event/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA recorded recognition of a person — name acknowledged, preference anticipated, relationship remembered, gesture offered, upgrade provided, amenity provided, personal note left, birthday or anniversary marked, repeat visit acknowledged, VIP treatment initiated. Always-on across all loyalty archetypes — the program_type does not gate recognition; Aman runs recognition-only and Maybourne runs LHW + deep internal recognition independently. `delivery_visibility` types the Aman invisible-attention vs Ritz visible-attention axis: the same recognition can be delivered visibly (a hand-written welcome card on arrival) or invisibly (the temperature set to the guest's preference before they enter the room). The pair with proposal 0002's `service_recovery_event` lets the read-side projection surface the operator's recognition-vs-recovery balance.", "operationId": "search_hospitality_recognition_event", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recognition_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "name_acknowledged", "preference_anticipated", "relationship_remembered", "gesture_offered", "upgrade_provided", "amenity_provided", "personal_note_left", "birthday_anniversary_marked", "repeat_visit_acknowledged", "vip_treatment_initiated", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delivery_visibility" }, "type": { "const": "eq" }, "value": { "enum": [ "visible_to_guest", "invisible_to_guest" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recognition_subject_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recognition_subject_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recognition_action_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recognition_action_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recogniser" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recogniser" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recogniser" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recogniser" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "comp_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "comp_category" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "comp_category" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "comp_category" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "comp_category" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "happened_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "happened_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "happened_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "stay_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "stay_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "stay_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "stay_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "recognition_kind", "delivery_visibility", "recognition_subject_text", "recognition_action_text", "recogniser", "comp_category", "happened_at", "stay_id" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.recognition_event" }, "properties": { "additionalProperties": false, "properties": { "comp_amount": { "description": "Comp amount when recognition includes value", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Recognition event comp amount", "type": "object" }, "comp_category": { "title": "Comp category (toolkit dictionary key)", "type": "string" }, "delivery_visibility": { "enum": [ "visible_to_guest", "invisible_to_guest" ], "title": "Delivery visibility", "type": "string" }, "happened_at": { "format": "date-time", "title": "When the recognition happened", "type": "string" }, "id": { "title": "Recognition event id", "type": "string" }, "recogniser": { "title": "Recogniser principal identifier", "type": "string" }, "recognition_action_text": { "title": "What the operator did", "type": "string" }, "recognition_kind": { "enum": [ "name_acknowledged", "preference_anticipated", "relationship_remembered", "gesture_offered", "upgrade_provided", "amenity_provided", "personal_note_left", "birthday_anniversary_marked", "repeat_visit_acknowledged", "vip_treatment_initiated", "other" ], "title": "Recognition kind", "type": "string" }, "recognition_subject_text": { "title": "What was recognised", "type": "string" }, "stay_id": { "title": "Stay context (when applicable)", "type": "string" } }, "required": [ "id", "recognition_kind", "delivery_visibility", "happened_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.recognition_event:read" ] } ], "summary": "Search Recognition event", "tags": [ "loyalty" ] } }, "/v1/object-types/hospitality.recovery_pattern_detection_run/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA property-scoped run parent for service-recovery pattern detection. Captures scan window, scan signals, agent provenance, status, and lifecycle counters.", "operationId": "get_hospitality_recovery_pattern_detection_run", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.recovery_pattern_detection_run" }, "properties": { "additionalProperties": false, "properties": { "agent_model": { "title": "Agent model", "type": "string" }, "agent_vendor": { "title": "Agent vendor", "type": "string" }, "agent_version": { "title": "Agent version", "type": "string" }, "applied_count": { "title": "Patterns applied", "type": "integer" }, "cadence": { "enum": [ "nightly", "weekly", "monthly", "event_triggered", "manual" ], "title": "Run cadence", "type": "string" }, "escalated_count": { "title": "Patterns escalated", "type": "integer" }, "expired_count": { "title": "Patterns expired", "type": "integer" }, "failure_reason": { "title": "Failure reason when status = failed", "type": "string" }, "finished_at": { "format": "date-time", "title": "Run finish", "type": "string" }, "id": { "title": "Run id", "type": "string" }, "patterns_count": { "title": "Patterns emitted", "type": "integer" }, "patterns_count_computed_at": { "format": "date-time", "title": "When counters were last refreshed", "type": "string" }, "rejected_count": { "title": "Patterns rejected", "type": "integer" }, "scan_method": { "title": "Detector method or rule-set description", "type": "string" }, "scan_signals": { "items": { "enum": [ "service_recovery_event", "pre_shift_lineup_event", "message_triage", "work_order", "housekeeping_task", "recognition_event", "review_aggregate" ], "type": "string" }, "title": "Signals included in this scan", "type": "array" }, "scan_window_end": { "format": "date-time", "title": "Scan window end", "type": "string" }, "scan_window_start": { "format": "date-time", "title": "Scan window start", "type": "string" }, "started_at": { "format": "date-time", "title": "Run start", "type": "string" }, "status": { "enum": [ "in_progress", "completed", "failed" ], "title": "Run status", "type": "string" } }, "required": [ "id", "started_at", "status", "cadence", "agent_vendor", "agent_version", "scan_window_start", "scan_window_end", "scan_signals", "scan_method" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.recovery_pattern_detection_run:read" ] } ], "summary": "Read Recovery pattern detection run", "tags": [ "recovery_pattern_detection" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.recovery_pattern_detection_run/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA property-scoped run parent for service-recovery pattern detection. Captures scan window, scan signals, agent provenance, status, and lifecycle counters.", "operationId": "get_hospitality_recovery_pattern_detection_run_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.recovery_pattern_detection_run" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.recovery_pattern_detection_run:read" ] } ], "summary": "Read Recovery pattern detection run as of a watermark", "tags": [ "recovery_pattern_detection" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.recovery_pattern_detection_run/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA property-scoped run parent for service-recovery pattern detection. Captures scan window, scan signals, agent provenance, status, and lifecycle counters.", "operationId": "list_links_hospitality_recovery_pattern_detection_run", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.recovery_pattern_detection_run:read" ] } ], "summary": "List links of Recovery pattern detection run", "tags": [ "recovery_pattern_detection" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.pattern_part_of_run", "hospitality.link.recovery_pattern_run_for_property" ] } } ] }, "/v1/object-types/hospitality.recovery_pattern_detection_run/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA property-scoped run parent for service-recovery pattern detection. Captures scan window, scan signals, agent provenance, status, and lifecycle counters.", "operationId": "traverse_hospitality_recovery_pattern_detection_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.pattern_part_of_run", "hospitality.link.recovery_pattern_run_for_property" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.recovery_pattern_detection_run:read" ] } ], "summary": "Traverse from Recovery pattern detection run", "tags": [ "recovery_pattern_detection" ] } }, "/v1/object-types/hospitality.recovery_pattern_detection_run/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA property-scoped run parent for service-recovery pattern detection. Captures scan window, scan signals, agent provenance, status, and lifecycle counters.", "operationId": "search_hospitality_recovery_pattern_detection_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "finished_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "finished_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "finished_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "in_progress", "completed", "failed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cadence" }, "type": { "const": "eq" }, "value": { "enum": [ "nightly", "weekly", "monthly", "event_triggered", "manual" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_vendor" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_vendor" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_vendor" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_vendor" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_version" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_version" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_version" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_version" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_model" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_model" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_model" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "agent_model" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "scan_window_start" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "scan_window_start" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "scan_window_start" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "scan_window_end" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "scan_window_end" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "scan_window_end" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "scan_signals" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "service_recovery_event", "pre_shift_lineup_event", "message_triage", "work_order", "housekeeping_task", "recognition_event", "review_aggregate" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "scan_method" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "scan_method" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "scan_method" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "scan_method" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "patterns_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "patterns_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "patterns_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejected_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejected_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejected_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "escalated_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "escalated_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "escalated_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expired_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expired_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expired_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "patterns_count_computed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "patterns_count_computed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "patterns_count_computed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "failure_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "failure_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "started_at", "finished_at", "status", "cadence", "agent_vendor", "agent_version", "agent_model", "scan_window_start", "scan_window_end", "scan_method", "patterns_count", "applied_count", "rejected_count", "escalated_count", "expired_count", "patterns_count_computed_at", "failure_reason" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.recovery_pattern_detection_run" }, "properties": { "additionalProperties": false, "properties": { "agent_model": { "title": "Agent model", "type": "string" }, "agent_vendor": { "title": "Agent vendor", "type": "string" }, "agent_version": { "title": "Agent version", "type": "string" }, "applied_count": { "title": "Patterns applied", "type": "integer" }, "cadence": { "enum": [ "nightly", "weekly", "monthly", "event_triggered", "manual" ], "title": "Run cadence", "type": "string" }, "escalated_count": { "title": "Patterns escalated", "type": "integer" }, "expired_count": { "title": "Patterns expired", "type": "integer" }, "failure_reason": { "title": "Failure reason when status = failed", "type": "string" }, "finished_at": { "format": "date-time", "title": "Run finish", "type": "string" }, "id": { "title": "Run id", "type": "string" }, "patterns_count": { "title": "Patterns emitted", "type": "integer" }, "patterns_count_computed_at": { "format": "date-time", "title": "When counters were last refreshed", "type": "string" }, "rejected_count": { "title": "Patterns rejected", "type": "integer" }, "scan_method": { "title": "Detector method or rule-set description", "type": "string" }, "scan_signals": { "items": { "enum": [ "service_recovery_event", "pre_shift_lineup_event", "message_triage", "work_order", "housekeeping_task", "recognition_event", "review_aggregate" ], "type": "string" }, "title": "Signals included in this scan", "type": "array" }, "scan_window_end": { "format": "date-time", "title": "Scan window end", "type": "string" }, "scan_window_start": { "format": "date-time", "title": "Scan window start", "type": "string" }, "started_at": { "format": "date-time", "title": "Run start", "type": "string" }, "status": { "enum": [ "in_progress", "completed", "failed" ], "title": "Run status", "type": "string" } }, "required": [ "id", "started_at", "status", "cadence", "agent_vendor", "agent_version", "scan_window_start", "scan_window_end", "scan_signals", "scan_method" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.recovery_pattern_detection_run:read" ] } ], "summary": "Search Recovery pattern detection run", "tags": [ "recovery_pattern_detection" ] } }, "/v1/object-types/hospitality.recovery_toolkit/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe property's comp-authority policy + recovery framework + top-cover principle. The `policy_kind` enum spans the observed-in-production patterns (Ritz `flat_universal`, USHG `per_role_per_shift_cumulative`, Aman `training_and_tenure_based`, the strict `escalation_only`); the `role_authorities` array carries per-role rules for the policies that need them (per-role-per-incident, per-role-mixed). The original sketch of 'comp authority per role' could not admit the universal, per-shift cumulative, training-based, or escalation-only shapes — the enum + array pair is the research-led correction. See `products/forge/spec/proposals/0002-service-philosophy.md` §3.3 and §10 open question 1 for reviewer context. Soft validators on over-limit recoveries warn but don't block — over-limit recoveries are exactly the data the operator most needs and would otherwise hide (the literature is explicit that hard blocks produce 'ghost recoveries' where the front line works around the system).", "operationId": "get_hospitality_recovery_toolkit", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.recovery_toolkit" }, "properties": { "additionalProperties": false, "properties": { "comp_category_definitions": { "title": "Property-specific comp categories" }, "flat_universal_per_guest_per_day": { "description": "Flat universal per-guest-per-day cap", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Recovery toolkit flat universal per guest per day", "type": "object" }, "flat_universal_per_incident_limit": { "description": "Flat universal per-incident comp limit", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Recovery toolkit flat universal per incident limit", "type": "object" }, "id": { "title": "Toolkit id", "type": "string" }, "policy_kind": { "enum": [ "flat_universal", "per_role_per_incident", "per_role_per_shift_cumulative", "per_role_mixed", "training_and_tenure_based", "escalation_only" ], "title": "Comp authority policy kind", "type": "string" }, "recovery_process_framework": { "enum": [ "ritz_three_steps", "ushg_5_as", "aman_unscripted", "custom" ], "title": "Recovery process framework", "type": "string" }, "role_authorities": { "description": "Per-role comp authority rules", "items": { "properties": { "comp_categories_allowed": { "items": { "enum": [ "room_night", "food_beverage", "spa", "retail", "parking", "other" ], "type": "string" }, "type": "array" }, "escalation_required_above": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "per_guest_per_day": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "per_incident_limit": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "per_shift_cumulative": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "role_code": { "type": "string" } }, "required": [ "role_code" ], "type": "object" }, "title": "Recovery toolkit role authorities", "type": "array" }, "top_cover_principle_text": { "title": "Top-cover principle", "type": "string" } }, "required": [ "id", "policy_kind", "recovery_process_framework", "top_cover_principle_text" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.recovery_toolkit:read" ] } ], "summary": "Read Recovery toolkit", "tags": [ "service_philosophy" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.recovery_toolkit/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe property's comp-authority policy + recovery framework + top-cover principle. The `policy_kind` enum spans the observed-in-production patterns (Ritz `flat_universal`, USHG `per_role_per_shift_cumulative`, Aman `training_and_tenure_based`, the strict `escalation_only`); the `role_authorities` array carries per-role rules for the policies that need them (per-role-per-incident, per-role-mixed). The original sketch of 'comp authority per role' could not admit the universal, per-shift cumulative, training-based, or escalation-only shapes — the enum + array pair is the research-led correction. See `products/forge/spec/proposals/0002-service-philosophy.md` §3.3 and §10 open question 1 for reviewer context. Soft validators on over-limit recoveries warn but don't block — over-limit recoveries are exactly the data the operator most needs and would otherwise hide (the literature is explicit that hard blocks produce 'ghost recoveries' where the front line works around the system).", "operationId": "get_hospitality_recovery_toolkit_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.recovery_toolkit" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.recovery_toolkit:read" ] } ], "summary": "Read Recovery toolkit as of a watermark", "tags": [ "service_philosophy" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.recovery_toolkit/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe property's comp-authority policy + recovery framework + top-cover principle. The `policy_kind` enum spans the observed-in-production patterns (Ritz `flat_universal`, USHG `per_role_per_shift_cumulative`, Aman `training_and_tenure_based`, the strict `escalation_only`); the `role_authorities` array carries per-role rules for the policies that need them (per-role-per-incident, per-role-mixed). The original sketch of 'comp authority per role' could not admit the universal, per-shift cumulative, training-based, or escalation-only shapes — the enum + array pair is the research-led correction. See `products/forge/spec/proposals/0002-service-philosophy.md` §3.3 and §10 open question 1 for reviewer context. Soft validators on over-limit recoveries warn but don't block — over-limit recoveries are exactly the data the operator most needs and would otherwise hide (the literature is explicit that hard blocks produce 'ghost recoveries' where the front line works around the system).", "operationId": "list_links_hospitality_recovery_toolkit", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.recovery_toolkit:read" ] } ], "summary": "List links of Recovery toolkit", "tags": [ "service_philosophy" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.philosophy_has_recovery_toolkit" ] } } ] }, "/v1/object-types/hospitality.recovery_toolkit/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe property's comp-authority policy + recovery framework + top-cover principle. The `policy_kind` enum spans the observed-in-production patterns (Ritz `flat_universal`, USHG `per_role_per_shift_cumulative`, Aman `training_and_tenure_based`, the strict `escalation_only`); the `role_authorities` array carries per-role rules for the policies that need them (per-role-per-incident, per-role-mixed). The original sketch of 'comp authority per role' could not admit the universal, per-shift cumulative, training-based, or escalation-only shapes — the enum + array pair is the research-led correction. See `products/forge/spec/proposals/0002-service-philosophy.md` §3.3 and §10 open question 1 for reviewer context. Soft validators on over-limit recoveries warn but don't block — over-limit recoveries are exactly the data the operator most needs and would otherwise hide (the literature is explicit that hard blocks produce 'ghost recoveries' where the front line works around the system).", "operationId": "traverse_hospitality_recovery_toolkit", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.philosophy_has_recovery_toolkit" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.recovery_toolkit:read" ] } ], "summary": "Traverse from Recovery toolkit", "tags": [ "service_philosophy" ] } }, "/v1/object-types/hospitality.recovery_toolkit/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe property's comp-authority policy + recovery framework + top-cover principle. The `policy_kind` enum spans the observed-in-production patterns (Ritz `flat_universal`, USHG `per_role_per_shift_cumulative`, Aman `training_and_tenure_based`, the strict `escalation_only`); the `role_authorities` array carries per-role rules for the policies that need them (per-role-per-incident, per-role-mixed). The original sketch of 'comp authority per role' could not admit the universal, per-shift cumulative, training-based, or escalation-only shapes — the enum + array pair is the research-led correction. See `products/forge/spec/proposals/0002-service-philosophy.md` §3.3 and §10 open question 1 for reviewer context. Soft validators on over-limit recoveries warn but don't block — over-limit recoveries are exactly the data the operator most needs and would otherwise hide (the literature is explicit that hard blocks produce 'ghost recoveries' where the front line works around the system).", "operationId": "search_hospitality_recovery_toolkit", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "policy_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "flat_universal", "per_role_per_incident", "per_role_per_shift_cumulative", "per_role_mixed", "training_and_tenure_based", "escalation_only" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "flat_universal_per_incident_limit" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "flat_universal_per_guest_per_day" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "role_authorities" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "comp_categories_allowed": { "items": { "enum": [ "room_night", "food_beverage", "spa", "retail", "parking", "other" ], "type": "string" }, "type": "array" }, "escalation_required_above": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "per_guest_per_day": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "per_incident_limit": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "per_shift_cumulative": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "role_code": { "type": "string" } }, "required": [ "role_code" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recovery_process_framework" }, "type": { "const": "eq" }, "value": { "enum": [ "ritz_three_steps", "ushg_5_as", "aman_unscripted", "custom" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "comp_category_definitions" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "top_cover_principle_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "top_cover_principle_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "policy_kind", "recovery_process_framework", "top_cover_principle_text" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.recovery_toolkit" }, "properties": { "additionalProperties": false, "properties": { "comp_category_definitions": { "title": "Property-specific comp categories" }, "flat_universal_per_guest_per_day": { "description": "Flat universal per-guest-per-day cap", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Recovery toolkit flat universal per guest per day", "type": "object" }, "flat_universal_per_incident_limit": { "description": "Flat universal per-incident comp limit", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Recovery toolkit flat universal per incident limit", "type": "object" }, "id": { "title": "Toolkit id", "type": "string" }, "policy_kind": { "enum": [ "flat_universal", "per_role_per_incident", "per_role_per_shift_cumulative", "per_role_mixed", "training_and_tenure_based", "escalation_only" ], "title": "Comp authority policy kind", "type": "string" }, "recovery_process_framework": { "enum": [ "ritz_three_steps", "ushg_5_as", "aman_unscripted", "custom" ], "title": "Recovery process framework", "type": "string" }, "role_authorities": { "description": "Per-role comp authority rules", "items": { "properties": { "comp_categories_allowed": { "items": { "enum": [ "room_night", "food_beverage", "spa", "retail", "parking", "other" ], "type": "string" }, "type": "array" }, "escalation_required_above": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "per_guest_per_day": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "per_incident_limit": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "per_shift_cumulative": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "role_code": { "type": "string" } }, "required": [ "role_code" ], "type": "object" }, "title": "Recovery toolkit role authorities", "type": "array" }, "top_cover_principle_text": { "title": "Top-cover principle", "type": "string" } }, "required": [ "id", "policy_kind", "recovery_process_framework", "top_cover_principle_text" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.recovery_toolkit:read" ] } ], "summary": "Search Recovery toolkit", "tags": [ "service_philosophy" ] } }, "/v1/object-types/hospitality.registration_card/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe registration card a guest signed at the desk on check-in: the house's terms as they were shown, verbatim, who signed and when, and the signature's strokes as SVG path data. A chargeback's evidence packet attaches the current card as `customer_signature`. One current card per stay; signing again supersedes it.", "operationId": "get_hospitality_registration_card", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.registration_card" }, "properties": { "additionalProperties": false, "properties": { "captured_by": { "title": "The desk principal that recorded the card (`principal.stable_id()`)", "type": "string" }, "device_label": { "title": "The desk device the guest signed on, as the desk names it", "type": "string" }, "id": { "title": "Card id", "type": "string" }, "signature_height": { "title": "The height of the pad the strokes were drawn on, in the strokes' units", "type": "integer" }, "signature_svg_paths": { "title": "The signature's strokes as SVG path data (`M x y L x y …`, in the pad's own units; at most 64 KB)", "type": "string" }, "signature_width": { "title": "The width of the pad the strokes were drawn on, in the strokes' units", "type": "integer" }, "signed_at": { "format": "date-time", "title": "When the guest signed (the kernel's clock at the desk's write)", "type": "string" }, "signer_name": { "title": "The name the guest signed under, as the desk confirmed it", "type": "string" }, "status": { "enum": [ "current", "superseded" ], "title": "Status", "type": "string" }, "superseded_at": { "format": "date-time", "title": "When a later signing on the same stay replaced this card", "type": "string" }, "terms_text": { "title": "The terms the guest was shown above the signature, verbatim", "type": "string" }, "terms_version": { "title": "Which version of the house's terms was shown — a label or a hash of the text, so two cards signed under the same wording say so", "type": "string" } }, "required": [ "id", "status", "signed_at", "terms_version", "terms_text" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.registration_card:read" ] } ], "summary": "Read Registration card", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.registration_card/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe registration card a guest signed at the desk on check-in: the house's terms as they were shown, verbatim, who signed and when, and the signature's strokes as SVG path data. A chargeback's evidence packet attaches the current card as `customer_signature`. One current card per stay; signing again supersedes it.", "operationId": "get_hospitality_registration_card_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.registration_card" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.registration_card:read" ] } ], "summary": "Read Registration card as of a watermark", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.registration_card/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe registration card a guest signed at the desk on check-in: the house's terms as they were shown, verbatim, who signed and when, and the signature's strokes as SVG path data. A chargeback's evidence packet attaches the current card as `customer_signature`. One current card per stay; signing again supersedes it.", "operationId": "list_links_hospitality_registration_card", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.registration_card:read" ] } ], "summary": "List links of Registration card", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.registration_card_for_reservation", "hospitality.link.registration_card_for_stay" ] } } ] }, "/v1/object-types/hospitality.registration_card/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe registration card a guest signed at the desk on check-in: the house's terms as they were shown, verbatim, who signed and when, and the signature's strokes as SVG path data. A chargeback's evidence packet attaches the current card as `customer_signature`. One current card per stay; signing again supersedes it.", "operationId": "traverse_hospitality_registration_card", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.registration_card_for_reservation", "hospitality.link.registration_card_for_stay" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.registration_card:read" ] } ], "summary": "Traverse from Registration card", "tags": [ "booking" ] } }, "/v1/object-types/hospitality.registration_card/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe registration card a guest signed at the desk on check-in: the house's terms as they were shown, verbatim, who signed and when, and the signature's strokes as SVG path data. A chargeback's evidence packet attaches the current card as `customer_signature`. One current card per stay; signing again supersedes it.", "operationId": "search_hospitality_registration_card", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "current", "superseded" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "signed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "signed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "signed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "signer_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "signer_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "signer_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "signer_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "terms_version" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "terms_version" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "terms_version" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "terms_version" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "terms_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "terms_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "signature_svg_paths" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "signature_svg_paths" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "signature_width" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "signature_width" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "signature_width" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "signature_height" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "signature_height" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "signature_height" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "captured_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "captured_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "captured_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "captured_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "device_label" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "device_label" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "device_label" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "device_label" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "superseded_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "superseded_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "superseded_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "status", "signed_at", "signer_name", "terms_version", "terms_text", "signature_svg_paths", "signature_width", "signature_height", "captured_by", "device_label", "superseded_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.registration_card" }, "properties": { "additionalProperties": false, "properties": { "captured_by": { "title": "The desk principal that recorded the card (`principal.stable_id()`)", "type": "string" }, "device_label": { "title": "The desk device the guest signed on, as the desk names it", "type": "string" }, "id": { "title": "Card id", "type": "string" }, "signature_height": { "title": "The height of the pad the strokes were drawn on, in the strokes' units", "type": "integer" }, "signature_svg_paths": { "title": "The signature's strokes as SVG path data (`M x y L x y …`, in the pad's own units; at most 64 KB)", "type": "string" }, "signature_width": { "title": "The width of the pad the strokes were drawn on, in the strokes' units", "type": "integer" }, "signed_at": { "format": "date-time", "title": "When the guest signed (the kernel's clock at the desk's write)", "type": "string" }, "signer_name": { "title": "The name the guest signed under, as the desk confirmed it", "type": "string" }, "status": { "enum": [ "current", "superseded" ], "title": "Status", "type": "string" }, "superseded_at": { "format": "date-time", "title": "When a later signing on the same stay replaced this card", "type": "string" }, "terms_text": { "title": "The terms the guest was shown above the signature, verbatim", "type": "string" }, "terms_version": { "title": "Which version of the house's terms was shown — a label or a hash of the text, so two cards signed under the same wording say so", "type": "string" } }, "required": [ "id", "status", "signed_at", "terms_version", "terms_text" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.registration_card:read" ] } ], "summary": "Search Registration card", "tags": [ "booking" ] } }, "/v1/object-types/hospitality.reservation/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA confirmed or held intent to occupy one or more rooms over a set of nights. Linked to a property, a primary guest, optionally a company, a rate plan, and a room type.", "operationId": "get_hospitality_reservation", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" }, "properties": { "additionalProperties": false, "properties": { "adults": { "title": "Adults", "type": "integer" }, "arrival_date": { "format": "date", "title": "Arrival date", "type": "string" }, "booked_at": { "format": "date-time", "title": "Booked at", "type": "string" }, "cancellation_fee_amount": { "description": "Cancellation fee", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Reservation cancellation fee amount", "type": "object" }, "cancellation_fee_attempt_card_ref": { "format": "uuid", "title": "The stored card an open cancellation fee collection is charging — drawn again by its retry whatever the house's merchant account did in between", "type": "string", "x-aerandil-references": "hospitality.payment_card" }, "cancellation_fee_attempt_open_at": { "format": "date-time", "title": "Set while a collection of the cancellation fee is open — written before the processor is asked, cleared when its outcome is recorded; an open attempt is asked again under the same key", "type": "string" }, "cancellation_fee_attempt_provider_card_ref": { "title": "The processor payment method an open cancellation fee collection is charging — the card's `provider_card_ref` when the attempt opened", "type": "string" }, "cancellation_fee_attempt_provider_customer_ref": { "title": "The processor customer an open cancellation fee collection is charging — the card's `provider_customer_ref` when the attempt opened", "type": "string" }, "cancellation_fee_due_at": { "format": "date-time", "title": "Cancellation fee due at (frozen at booking)", "type": "string" }, "cancellation_fee_status": { "enum": [ "assessed", "collected", "authentication_required", "uncollectible" ], "title": "Cancellation fee status", "type": "string" }, "cancellation_policy_ref": { "format": "uuid", "title": "Cancellation policy (live ref)", "type": "string", "x-aerandil-references": "hospitality.cancellation_policy" }, "cancellation_policy_text": { "title": "Cancellation policy text (snapshot at booking)", "type": "string" }, "cancellation_reason": { "title": "Cancellation reason (set by cancel_reservation)", "type": "string" }, "cancellation_schedule": { "description": "Cancellation ladder resolved to money (frozen at booking)", "items": { "properties": { "effective_from": { "format": "date-time", "type": "string" }, "penalty_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "penalty_kind": { "enum": [ "absolute", "percent_of_total", "n_nights" ], "type": "string" }, "tier_index": { "type": "integer" } }, "required": [ "effective_from", "penalty_amount", "tier_index", "penalty_kind" ], "type": "object" }, "title": "Reservation cancellation schedule", "type": "array" }, "cancelled_at": { "format": "date-time", "title": "Cancelled at", "type": "string" }, "channel_reference": { "title": "External channel reference", "type": "string" }, "children": { "title": "Children", "type": "integer" }, "confirmation_number": { "title": "Confirmation number", "type": "string" }, "departure_date": { "format": "date", "title": "Departure date", "type": "string" }, "deposit_due_at": { "format": "date-time", "title": "Deposit due by", "type": "string" }, "deposit_paid_amount": { "description": "Deposit paid (accumulating)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Reservation deposit paid amount", "type": "object" }, "deposit_policy_ref": { "format": "uuid", "title": "Deposit policy (frozen at derivation)", "type": "string", "x-aerandil-references": "hospitality.deposit_policy" }, "deposit_required_amount": { "description": "Deposit required", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Reservation deposit required amount", "type": "object" }, "deposit_returned_amount": { "description": "Deposit returned (accumulating)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Reservation deposit returned amount", "type": "object" }, "expected_total": { "description": "Expected total revenue", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Reservation expected total", "type": "object" }, "external_ref": { "title": "Source-system key for connector-landed reservations", "type": "string" }, "fraud_warning_at": { "description": "Set by `record_fraud_warning` when an issuer's early fraud warning reaches a payment behind this booking (the payment carries the warning itself). Before arrival the desk decides whether to cancel and refund while the room can still be resold; a voided hold leaves the booking without its guarantee.", "format": "date-time", "title": "When an issuer warned of fraud on a payment for this booking", "type": "string" }, "fraud_warning_response": { "enum": [ "hold_voided", "refunded", "desk_review", "not_actionable" ], "title": "What the card rail did about that warning", "type": "string" }, "guarantee": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "title": "Guarantee", "type": "string" }, "hold_expires_at": { "format": "date-time", "title": "Hold expires at", "type": "string" }, "market_segment": { "enum": [ "transient", "group", "contract" ], "title": "Market segment", "type": "string" }, "no_show_fee_amount": { "description": "No-show fee", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Reservation no show fee amount", "type": "object" }, "no_show_fee_attempt_card_ref": { "format": "uuid", "title": "The stored card an open no-show fee collection is charging — drawn again by its retry whatever the house's merchant account did in between", "type": "string", "x-aerandil-references": "hospitality.payment_card" }, "no_show_fee_attempt_open_at": { "format": "date-time", "title": "Set while a collection of the no-show fee is open — written before the processor is asked, cleared when its outcome is recorded; an open attempt is asked again under the same key", "type": "string" }, "no_show_fee_attempt_provider_card_ref": { "title": "The processor payment method an open no-show fee collection is charging — the card's `provider_card_ref` when the attempt opened", "type": "string" }, "no_show_fee_attempt_provider_customer_ref": { "title": "The processor customer an open no-show fee collection is charging — the card's `provider_customer_ref` when the attempt opened", "type": "string" }, "no_show_fee_status": { "enum": [ "assessed", "collected", "authentication_required", "uncollectible" ], "title": "No-show fee status", "type": "string" }, "no_show_posted_amount": { "description": "No-show amount posted", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Reservation no show posted amount", "type": "object" }, "no_show_posting_basis": { "enum": [ "all_nights", "first_night", "deposit_only", "none" ], "title": "No-show posting basis applied", "type": "string" }, "no_show_reason": { "title": "No-show reason (set by mark_reservation_no_show)", "type": "string" }, "prepayment_status": { "enum": [ "not_required", "required", "invoiced", "partially_paid", "paid", "applied_to_folio", "refunded", "forfeited" ], "title": "Prepayment status", "type": "string" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "Source", "type": "string" }, "special_requests": { "title": "Special requests", "type": "string" }, "status": { "enum": [ "held", "confirmed", "modified", "in_house", "checked_out", "cancelled", "no_show" ], "title": "Status", "type": "string" }, "stay_context_kind": { "enum": [ "leisure", "business", "anniversary", "wellness_retreat", "family", "event_attendance", "bleisure", "other" ], "title": "Stay context kind", "type": "string" }, "stay_context_notes": { "title": "Stay context notes", "type": "string" }, "visitor_id": { "title": "Booking engine visitor", "type": "string" } }, "required": [ "arrival_date", "departure_date", "adults", "children", "status", "source", "guarantee", "booked_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.reservation:read" ] } ], "summary": "Read Reservation", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.reservation/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA confirmed or held intent to occupy one or more rooms over a set of nights. Linked to a property, a primary guest, optionally a company, a rate plan, and a room type.", "operationId": "get_hospitality_reservation_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.reservation" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.reservation:read" ] } ], "summary": "Read Reservation as of a watermark", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.reservation/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA confirmed or held intent to occupy one or more rooms over a set of nights. Linked to a property, a primary guest, optionally a company, a rate plan, and a room type.", "operationId": "list_links_hospitality_reservation", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.reservation:read" ] } ], "summary": "List links of Reservation", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.booking_origin_for_reservation", "hospitality.link.commission_detail_for_reservation", "hospitality.link.fraud_assessment_chained_action_target", "hospitality.link.fraud_assessment_for_reservation", "hospitality.link.group_request_converts_to_reservation", "hospitality.link.guest_conversation_anchored_to_reservation", "hospitality.link.payment_card_for_reservation", "hospitality.link.payment_for_reservation", "hospitality.link.payment_request_for_reservation", "hospitality.link.registration_card_for_reservation", "hospitality.link.reservation_booked_in_session", "hospitality.link.reservation_delivery_produced_reservation", "hospitality.link.reservation_for_company", "hospitality.link.reservation_for_guest", "hospitality.link.reservation_for_property", "hospitality.link.reservation_for_room_type", "hospitality.link.reservation_has_folio", "hospitality.link.reservation_has_room", "hospitality.link.reservation_has_stay", "hospitality.link.reservation_has_tax_exemption", "hospitality.link.reservation_in_share_group", "hospitality.link.reservation_includes_package", "hospitality.link.reservation_picked_up_from_block", "hospitality.link.reservation_uses_cancellation_policy", "hospitality.link.reservation_uses_rate_plan", "hospitality.link.reservation_via_channel", "hospitality.link.room_queue_entry_for_reservation", "hospitality.link.stored_object_for_reservation", "hospitality.link.waitlist_entry_became_reservation", "hospitality.link.workflow_run_targets_reservation" ] } } ] }, "/v1/object-types/hospitality.reservation/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA confirmed or held intent to occupy one or more rooms over a set of nights. Linked to a property, a primary guest, optionally a company, a rate plan, and a room type.", "operationId": "traverse_hospitality_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.booking_origin_for_reservation", "hospitality.link.commission_detail_for_reservation", "hospitality.link.fraud_assessment_chained_action_target", "hospitality.link.fraud_assessment_for_reservation", "hospitality.link.group_request_converts_to_reservation", "hospitality.link.guest_conversation_anchored_to_reservation", "hospitality.link.payment_card_for_reservation", "hospitality.link.payment_for_reservation", "hospitality.link.payment_request_for_reservation", "hospitality.link.registration_card_for_reservation", "hospitality.link.reservation_booked_in_session", "hospitality.link.reservation_delivery_produced_reservation", "hospitality.link.reservation_for_company", "hospitality.link.reservation_for_guest", "hospitality.link.reservation_for_property", "hospitality.link.reservation_for_room_type", "hospitality.link.reservation_has_folio", "hospitality.link.reservation_has_room", "hospitality.link.reservation_has_stay", "hospitality.link.reservation_has_tax_exemption", "hospitality.link.reservation_in_share_group", "hospitality.link.reservation_includes_package", "hospitality.link.reservation_picked_up_from_block", "hospitality.link.reservation_uses_cancellation_policy", "hospitality.link.reservation_uses_rate_plan", "hospitality.link.reservation_via_channel", "hospitality.link.room_queue_entry_for_reservation", "hospitality.link.stored_object_for_reservation", "hospitality.link.waitlist_entry_became_reservation", "hospitality.link.workflow_run_targets_reservation" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.reservation:read" ] } ], "summary": "Traverse from Reservation", "tags": [ "booking" ] } }, "/v1/object-types/hospitality.reservation/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA confirmed or held intent to occupy one or more rooms over a set of nights. Linked to a property, a primary guest, optionally a company, a rate plan, and a room type.", "operationId": "search_hospitality_reservation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "confirmation_number" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confirmation_number" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confirmation_number" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confirmation_number" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "arrival_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "arrival_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "arrival_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "departure_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "departure_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "departure_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "adults" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "adults" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "adults" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "children" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "children" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "children" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "held", "confirmed", "modified", "in_house", "checked_out", "cancelled", "no_show" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source" }, "type": { "const": "eq" }, "value": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "market_segment" }, "type": { "const": "eq" }, "value": { "enum": [ "transient", "group", "contract" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "channel_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "channel_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "channel_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "channel_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "visitor_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "visitor_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "visitor_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "visitor_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expected_total" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "guarantee" }, "type": { "const": "eq" }, "value": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "special_requests" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "special_requests" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "booked_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "booked_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "booked_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "deposit_required_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "deposit_paid_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "deposit_returned_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "deposit_due_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "deposit_due_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "deposit_due_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "prepayment_status" }, "type": { "const": "eq" }, "value": { "enum": [ "not_required", "required", "invoiced", "partially_paid", "paid", "applied_to_folio", "refunded", "forfeited" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "no_show_fee_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "no_show_fee_status" }, "type": { "const": "eq" }, "value": { "enum": [ "assessed", "collected", "authentication_required", "uncollectible" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "no_show_fee_attempt_card_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.payment_card" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "no_show_fee_attempt_open_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "no_show_fee_attempt_open_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "no_show_fee_attempt_open_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "no_show_fee_attempt_provider_card_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "no_show_fee_attempt_provider_card_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "no_show_fee_attempt_provider_card_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "no_show_fee_attempt_provider_card_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "no_show_fee_attempt_provider_customer_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "no_show_fee_attempt_provider_customer_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "no_show_fee_attempt_provider_customer_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "no_show_fee_attempt_provider_customer_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "no_show_posting_basis" }, "type": { "const": "eq" }, "value": { "enum": [ "all_nights", "first_night", "deposit_only", "none" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "no_show_posted_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "deposit_policy_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.deposit_policy" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_expires_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_expires_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_expires_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_policy_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.cancellation_policy" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_policy_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_policy_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_fee_due_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_fee_due_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_fee_due_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_fee_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_schedule" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "effective_from": { "format": "date-time", "type": "string" }, "penalty_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "penalty_kind": { "enum": [ "absolute", "percent_of_total", "n_nights" ], "type": "string" }, "tier_index": { "type": "integer" } }, "required": [ "effective_from", "penalty_amount", "tier_index", "penalty_kind" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_fee_status" }, "type": { "const": "eq" }, "value": { "enum": [ "assessed", "collected", "authentication_required", "uncollectible" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "stay_context_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "leisure", "business", "anniversary", "wellness_retreat", "family", "event_attendance", "bleisure", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "stay_context_notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "stay_context_notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "no_show_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "no_show_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancelled_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancelled_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancelled_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fraud_warning_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fraud_warning_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fraud_warning_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fraud_warning_response" }, "type": { "const": "eq" }, "value": { "enum": [ "hold_voided", "refunded", "desk_review", "not_actionable" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_fee_attempt_card_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.payment_card" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_fee_attempt_open_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_fee_attempt_open_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_fee_attempt_open_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_fee_attempt_provider_card_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_fee_attempt_provider_card_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_fee_attempt_provider_card_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_fee_attempt_provider_card_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_fee_attempt_provider_customer_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_fee_attempt_provider_customer_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_fee_attempt_provider_customer_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_fee_attempt_provider_customer_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "confirmation_number", "arrival_date", "departure_date", "adults", "children", "status", "source", "market_segment", "channel_reference", "visitor_id", "guarantee", "special_requests", "booked_at", "deposit_due_at", "prepayment_status", "no_show_fee_status", "no_show_fee_attempt_open_at", "no_show_fee_attempt_provider_card_ref", "no_show_fee_attempt_provider_customer_ref", "no_show_posting_basis", "hold_expires_at", "cancellation_policy_text", "cancellation_fee_due_at", "cancellation_fee_status", "stay_context_kind", "stay_context_notes", "cancellation_reason", "no_show_reason", "cancelled_at", "external_ref", "fraud_warning_at", "fraud_warning_response", "cancellation_fee_attempt_open_at", "cancellation_fee_attempt_provider_card_ref", "cancellation_fee_attempt_provider_customer_ref" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation" }, "properties": { "additionalProperties": false, "properties": { "adults": { "title": "Adults", "type": "integer" }, "arrival_date": { "format": "date", "title": "Arrival date", "type": "string" }, "booked_at": { "format": "date-time", "title": "Booked at", "type": "string" }, "cancellation_fee_amount": { "description": "Cancellation fee", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Reservation cancellation fee amount", "type": "object" }, "cancellation_fee_attempt_card_ref": { "format": "uuid", "title": "The stored card an open cancellation fee collection is charging — drawn again by its retry whatever the house's merchant account did in between", "type": "string", "x-aerandil-references": "hospitality.payment_card" }, "cancellation_fee_attempt_open_at": { "format": "date-time", "title": "Set while a collection of the cancellation fee is open — written before the processor is asked, cleared when its outcome is recorded; an open attempt is asked again under the same key", "type": "string" }, "cancellation_fee_attempt_provider_card_ref": { "title": "The processor payment method an open cancellation fee collection is charging — the card's `provider_card_ref` when the attempt opened", "type": "string" }, "cancellation_fee_attempt_provider_customer_ref": { "title": "The processor customer an open cancellation fee collection is charging — the card's `provider_customer_ref` when the attempt opened", "type": "string" }, "cancellation_fee_due_at": { "format": "date-time", "title": "Cancellation fee due at (frozen at booking)", "type": "string" }, "cancellation_fee_status": { "enum": [ "assessed", "collected", "authentication_required", "uncollectible" ], "title": "Cancellation fee status", "type": "string" }, "cancellation_policy_ref": { "format": "uuid", "title": "Cancellation policy (live ref)", "type": "string", "x-aerandil-references": "hospitality.cancellation_policy" }, "cancellation_policy_text": { "title": "Cancellation policy text (snapshot at booking)", "type": "string" }, "cancellation_reason": { "title": "Cancellation reason (set by cancel_reservation)", "type": "string" }, "cancellation_schedule": { "description": "Cancellation ladder resolved to money (frozen at booking)", "items": { "properties": { "effective_from": { "format": "date-time", "type": "string" }, "penalty_amount": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "penalty_kind": { "enum": [ "absolute", "percent_of_total", "n_nights" ], "type": "string" }, "tier_index": { "type": "integer" } }, "required": [ "effective_from", "penalty_amount", "tier_index", "penalty_kind" ], "type": "object" }, "title": "Reservation cancellation schedule", "type": "array" }, "cancelled_at": { "format": "date-time", "title": "Cancelled at", "type": "string" }, "channel_reference": { "title": "External channel reference", "type": "string" }, "children": { "title": "Children", "type": "integer" }, "confirmation_number": { "title": "Confirmation number", "type": "string" }, "departure_date": { "format": "date", "title": "Departure date", "type": "string" }, "deposit_due_at": { "format": "date-time", "title": "Deposit due by", "type": "string" }, "deposit_paid_amount": { "description": "Deposit paid (accumulating)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Reservation deposit paid amount", "type": "object" }, "deposit_policy_ref": { "format": "uuid", "title": "Deposit policy (frozen at derivation)", "type": "string", "x-aerandil-references": "hospitality.deposit_policy" }, "deposit_required_amount": { "description": "Deposit required", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Reservation deposit required amount", "type": "object" }, "deposit_returned_amount": { "description": "Deposit returned (accumulating)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Reservation deposit returned amount", "type": "object" }, "expected_total": { "description": "Expected total revenue", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Reservation expected total", "type": "object" }, "external_ref": { "title": "Source-system key for connector-landed reservations", "type": "string" }, "fraud_warning_at": { "description": "Set by `record_fraud_warning` when an issuer's early fraud warning reaches a payment behind this booking (the payment carries the warning itself). Before arrival the desk decides whether to cancel and refund while the room can still be resold; a voided hold leaves the booking without its guarantee.", "format": "date-time", "title": "When an issuer warned of fraud on a payment for this booking", "type": "string" }, "fraud_warning_response": { "enum": [ "hold_voided", "refunded", "desk_review", "not_actionable" ], "title": "What the card rail did about that warning", "type": "string" }, "guarantee": { "enum": [ "none", "hold", "credit_card", "deposit", "prepaid", "corporate_billed", "voucher" ], "title": "Guarantee", "type": "string" }, "hold_expires_at": { "format": "date-time", "title": "Hold expires at", "type": "string" }, "market_segment": { "enum": [ "transient", "group", "contract" ], "title": "Market segment", "type": "string" }, "no_show_fee_amount": { "description": "No-show fee", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Reservation no show fee amount", "type": "object" }, "no_show_fee_attempt_card_ref": { "format": "uuid", "title": "The stored card an open no-show fee collection is charging — drawn again by its retry whatever the house's merchant account did in between", "type": "string", "x-aerandil-references": "hospitality.payment_card" }, "no_show_fee_attempt_open_at": { "format": "date-time", "title": "Set while a collection of the no-show fee is open — written before the processor is asked, cleared when its outcome is recorded; an open attempt is asked again under the same key", "type": "string" }, "no_show_fee_attempt_provider_card_ref": { "title": "The processor payment method an open no-show fee collection is charging — the card's `provider_card_ref` when the attempt opened", "type": "string" }, "no_show_fee_attempt_provider_customer_ref": { "title": "The processor customer an open no-show fee collection is charging — the card's `provider_customer_ref` when the attempt opened", "type": "string" }, "no_show_fee_status": { "enum": [ "assessed", "collected", "authentication_required", "uncollectible" ], "title": "No-show fee status", "type": "string" }, "no_show_posted_amount": { "description": "No-show amount posted", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Reservation no show posted amount", "type": "object" }, "no_show_posting_basis": { "enum": [ "all_nights", "first_night", "deposit_only", "none" ], "title": "No-show posting basis applied", "type": "string" }, "no_show_reason": { "title": "No-show reason (set by mark_reservation_no_show)", "type": "string" }, "prepayment_status": { "enum": [ "not_required", "required", "invoiced", "partially_paid", "paid", "applied_to_folio", "refunded", "forfeited" ], "title": "Prepayment status", "type": "string" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "Source", "type": "string" }, "special_requests": { "title": "Special requests", "type": "string" }, "status": { "enum": [ "held", "confirmed", "modified", "in_house", "checked_out", "cancelled", "no_show" ], "title": "Status", "type": "string" }, "stay_context_kind": { "enum": [ "leisure", "business", "anniversary", "wellness_retreat", "family", "event_attendance", "bleisure", "other" ], "title": "Stay context kind", "type": "string" }, "stay_context_notes": { "title": "Stay context notes", "type": "string" }, "visitor_id": { "title": "Booking engine visitor", "type": "string" } }, "required": [ "arrival_date", "departure_date", "adults", "children", "status", "source", "guarantee", "booked_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.reservation:read" ] } ], "summary": "Search Reservation", "tags": [ "booking" ] } }, "/v1/object-types/hospitality.reservation_night/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne night of a `ReservationRoom`. Carries the rate amount, rate plan, and room type *for that specific night* — so a stay across a rate change, a comp night, or a rate-plan switch is naturally representable. Maps to OTA `Rate` elements at `EffectiveDate` granularity.", "operationId": "get_hospitality_reservation_night", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation_night" }, "properties": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" }, "complimentary": { "title": "Complimentary night", "type": "boolean" }, "id": { "title": "Reservation night id", "type": "string" }, "notes": { "title": "Notes", "type": "string" }, "rate_amount": { "description": "Rate amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Reservation night rate amount", "type": "object" } }, "required": [ "id", "business_date", "complimentary" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.reservation_night:read" ] } ], "summary": "Read Reservation night", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.reservation_night/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne night of a `ReservationRoom`. Carries the rate amount, rate plan, and room type *for that specific night* — so a stay across a rate change, a comp night, or a rate-plan switch is naturally representable. Maps to OTA `Rate` elements at `EffectiveDate` granularity.", "operationId": "get_hospitality_reservation_night_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.reservation_night" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.reservation_night:read" ] } ], "summary": "Read Reservation night as of a watermark", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.reservation_night/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne night of a `ReservationRoom`. Carries the rate amount, rate plan, and room type *for that specific night* — so a stay across a rate change, a comp night, or a rate-plan switch is naturally representable. Maps to OTA `Rate` elements at `EffectiveDate` granularity.", "operationId": "list_links_hospitality_reservation_night", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.reservation_night:read" ] } ], "summary": "List links of Reservation night", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.reservation_night_uses_rate_plan", "hospitality.link.reservation_room_has_night" ] } } ] }, "/v1/object-types/hospitality.reservation_night/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne night of a `ReservationRoom`. Carries the rate amount, rate plan, and room type *for that specific night* — so a stay across a rate change, a comp night, or a rate-plan switch is naturally representable. Maps to OTA `Rate` elements at `EffectiveDate` granularity.", "operationId": "traverse_hospitality_reservation_night", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.reservation_night_uses_rate_plan", "hospitality.link.reservation_room_has_night" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.reservation_night:read" ] } ], "summary": "Traverse from Reservation night", "tags": [ "booking" ] } }, "/v1/object-types/hospitality.reservation_night/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne night of a `ReservationRoom`. Carries the rate amount, rate plan, and room type *for that specific night* — so a stay across a rate change, a comp night, or a rate-plan switch is naturally representable. Maps to OTA `Rate` elements at `EffectiveDate` granularity.", "operationId": "search_hospitality_reservation_night", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rate_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "complimentary" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "business_date", "notes" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation_night" }, "properties": { "additionalProperties": false, "properties": { "business_date": { "format": "date", "title": "Business date", "type": "string" }, "complimentary": { "title": "Complimentary night", "type": "boolean" }, "id": { "title": "Reservation night id", "type": "string" }, "notes": { "title": "Notes", "type": "string" }, "rate_amount": { "description": "Rate amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Reservation night rate amount", "type": "object" } }, "required": [ "id", "business_date", "complimentary" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.reservation_night:read" ] } ], "summary": "Search Reservation night", "tags": [ "booking" ] } }, "/v1/object-types/hospitality.reservation_room/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne physical-room slice of a reservation. A reservation for '3 rooms x 4 nights' has three `ReservationRoom`s. Each carries the booked room type, optional assigned room, and the per-night detail it owns via `reservation_room_has_night`.", "operationId": "get_hospitality_reservation_room", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation_room" }, "properties": { "additionalProperties": false, "properties": { "adults": { "title": "Adults", "type": "integer" }, "cancellation_fee_amount": { "description": "Room cancellation fee", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Reservation room cancellation fee amount", "type": "object" }, "cancellation_fee_status": { "enum": [ "assessed", "collected", "authentication_required", "uncollectible" ], "title": "Room cancellation fee status", "type": "string" }, "cancellation_reason": { "title": "Room cancellation reason", "type": "string" }, "cancelled_at": { "format": "date-time", "title": "Room cancelled at", "type": "string" }, "children": { "title": "Children", "type": "integer" }, "day_use_rate": { "description": "Day-use slot rate", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Reservation room day use rate", "type": "object" }, "id": { "title": "Reservation room id", "type": "string" }, "index": { "title": "Index within reservation (1-based)", "type": "integer" }, "status": { "enum": [ "held", "confirmed", "assigned", "in_house", "checked_out", "cancelled" ], "title": "Status", "type": "string" } }, "required": [ "id", "index", "adults", "children", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.reservation_room:read" ] } ], "summary": "Read Reservation room", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.reservation_room/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne physical-room slice of a reservation. A reservation for '3 rooms x 4 nights' has three `ReservationRoom`s. Each carries the booked room type, optional assigned room, and the per-night detail it owns via `reservation_room_has_night`.", "operationId": "get_hospitality_reservation_room_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.reservation_room" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.reservation_room:read" ] } ], "summary": "Read Reservation room as of a watermark", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.reservation_room/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne physical-room slice of a reservation. A reservation for '3 rooms x 4 nights' has three `ReservationRoom`s. Each carries the booked room type, optional assigned room, and the per-night detail it owns via `reservation_room_has_night`.", "operationId": "list_links_hospitality_reservation_room", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.reservation_room:read" ] } ], "summary": "List links of Reservation room", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.reservation_has_room", "hospitality.link.reservation_room_assigned_to", "hospitality.link.reservation_room_charged_as_room_type", "hospitality.link.reservation_room_for_room_type", "hospitality.link.reservation_room_has_night", "hospitality.link.stay_for_reservation_room" ] } } ] }, "/v1/object-types/hospitality.reservation_room/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne physical-room slice of a reservation. A reservation for '3 rooms x 4 nights' has three `ReservationRoom`s. Each carries the booked room type, optional assigned room, and the per-night detail it owns via `reservation_room_has_night`.", "operationId": "traverse_hospitality_reservation_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.reservation_has_room", "hospitality.link.reservation_room_assigned_to", "hospitality.link.reservation_room_charged_as_room_type", "hospitality.link.reservation_room_for_room_type", "hospitality.link.reservation_room_has_night", "hospitality.link.stay_for_reservation_room" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.reservation_room:read" ] } ], "summary": "Traverse from Reservation room", "tags": [ "booking" ] } }, "/v1/object-types/hospitality.reservation_room/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne physical-room slice of a reservation. A reservation for '3 rooms x 4 nights' has three `ReservationRoom`s. Each carries the booked room type, optional assigned room, and the per-night detail it owns via `reservation_room_has_night`.", "operationId": "search_hospitality_reservation_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "index" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "index" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "index" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "adults" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "adults" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "adults" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "children" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "children" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "children" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "held", "confirmed", "assigned", "in_house", "checked_out", "cancelled" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "day_use_rate" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancelled_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancelled_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancelled_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_fee_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancellation_fee_status" }, "type": { "const": "eq" }, "value": { "enum": [ "assessed", "collected", "authentication_required", "uncollectible" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "index", "adults", "children", "status", "cancelled_at", "cancellation_reason", "cancellation_fee_status" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.reservation_room" }, "properties": { "additionalProperties": false, "properties": { "adults": { "title": "Adults", "type": "integer" }, "cancellation_fee_amount": { "description": "Room cancellation fee", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Reservation room cancellation fee amount", "type": "object" }, "cancellation_fee_status": { "enum": [ "assessed", "collected", "authentication_required", "uncollectible" ], "title": "Room cancellation fee status", "type": "string" }, "cancellation_reason": { "title": "Room cancellation reason", "type": "string" }, "cancelled_at": { "format": "date-time", "title": "Room cancelled at", "type": "string" }, "children": { "title": "Children", "type": "integer" }, "day_use_rate": { "description": "Day-use slot rate", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Reservation room day use rate", "type": "object" }, "id": { "title": "Reservation room id", "type": "string" }, "index": { "title": "Index within reservation (1-based)", "type": "integer" }, "status": { "enum": [ "held", "confirmed", "assigned", "in_house", "checked_out", "cancelled" ], "title": "Status", "type": "string" } }, "required": [ "id", "index", "adults", "children", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.reservation_room:read" ] } ], "summary": "Search Reservation room", "tags": [ "booking" ] } }, "/v1/object-types/hospitality.restriction_recommendation/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA typed sell-restriction recommendation issued by an agent against a scope (room type, rate plan, or the pair) over a date range: a closure, closed-to-arrival / departure, or a length-of- stay bound, with the reading that motivated it — the rooms left, the protection level, the demand and sell-up the recommender believes — frozen at issue time. Applying it authors a `rate_restriction` row through the same path a hand-posted restriction takes; a `lift` recommendation (the re-open) constrains nothing and its apply lifts the rows standing in its scope over its range, keeping them as history. The decision_* fields mutate exactly once on the transition out of `suggested`.", "operationId": "get_hospitality_restriction_recommendation", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.restriction_recommendation" }, "properties": { "additionalProperties": false, "properties": { "closed": { "title": "Hard stop-sell recommended", "type": "boolean" }, "closed_to_arrival": { "title": "Closed to arrival recommended", "type": "boolean" }, "closed_to_departure": { "title": "Closed to departure recommended", "type": "boolean" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Operator-facing confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Calibrated probability (0..=1) — set when the model emits one", "type": "string" }, "decided_at": { "format": "date-time", "title": "When the recommendation transitioned out of suggested", "type": "string" }, "decision_status": { "enum": [ "suggested", "applied", "modified_and_applied", "rejected", "expired", "superseded" ], "title": "Lifecycle state", "type": "string" }, "demand_forecast_rooms": { "format": "decimal", "title": "Unconstrained higher-rate demand the recommender believes for the first night, in rooms", "type": "string" }, "end_date": { "format": "date", "title": "Last night the restriction would cover (inclusive)", "type": "string" }, "expires_at": { "format": "date-time", "title": "After this, decision_status moves to expired", "type": "string" }, "expires_on": { "format": "date", "title": "The house business day this lapses after. When set, the house's open business date decides expiry (not the wall clock) and expires_at is the nominal end of that day in the house's timezone", "type": "string" }, "factors_considered": { "items": { "enum": [ "pickup_pace", "booking_curve", "competitive_set", "event_calendar", "historical_pattern", "segment_mix", "channel_mix", "length_of_stay_distribution", "cancellation_rate", "no_show_rate", "package_attachment", "group_displacement", "weather", "other" ], "type": "string" }, "title": "Signals the recommendation conditioned on (the strategy that fired)", "type": "array" }, "forecast_snapshot": { "description": "Forecast snapshot frozen at issue time (per §B.2)", "properties": { "ari_score": { "format": "decimal", "type": "string" }, "as_of": { "format": "date-time", "type": "string" }, "competitive_set_adr": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "competitive_set_occupancy_pct": { "format": "decimal", "type": "string" }, "event_calendar_signal": { "type": "string" }, "forecast_kind": { "enum": [ "internal_pms", "external_rms", "external_str_compset", "hybrid", "other" ], "type": "string" }, "mpi_score": { "format": "decimal", "type": "string" }, "on_books_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "on_books_rooms": { "type": "integer" }, "pickup_last_24h": { "type": "integer" }, "pickup_last_7d": { "type": "integer" }, "rgi_score": { "format": "decimal", "type": "string" }, "transient_adr_forecast": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "transient_rooms_forecast": { "type": "integer" } }, "required": [ "forecast_kind", "as_of" ], "title": "Restriction recommendation forecast snapshot", "type": "object" }, "id": { "title": "Recommendation id", "type": "string" }, "issued_at": { "format": "date-time", "title": "When the agent emitted the recommendation", "type": "string" }, "lift": { "title": "Recommend lifting what stands in the scope over the range (the re-open)", "type": "boolean" }, "max_length_of_stay": { "title": "Maximum length of stay recommended (nights)", "type": "integer" }, "min_length_of_stay": { "title": "Minimum length of stay recommended (nights)", "type": "integer" }, "protection_level": { "title": "Rooms the recommender wants kept for the higher rate (the protection level the restriction enforces)", "type": "integer" }, "rationale_text": { "title": "Human-readable explanation surfaced to operators", "type": "string" }, "rejection_reason": { "title": "Free-text reason set on reject", "type": "string" }, "rooms_remaining": { "title": "Rooms left to sell on the first night, at issue time", "type": "integer" }, "sell_up_rate": { "format": "decimal", "title": "Share of fenced-rate buyers believed to pay the higher rate once the fence closes (0..=1)", "type": "string" }, "start_date": { "format": "date", "title": "First night the restriction would cover", "type": "string" } }, "required": [ "id", "start_date", "end_date", "closed", "closed_to_arrival", "closed_to_departure", "confidence", "factors_considered", "issued_at", "expires_at", "decision_status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.restriction_recommendation:read" ] } ], "summary": "Read Restriction recommendation", "tags": [ "revenue_management" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.restriction_recommendation/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA typed sell-restriction recommendation issued by an agent against a scope (room type, rate plan, or the pair) over a date range: a closure, closed-to-arrival / departure, or a length-of- stay bound, with the reading that motivated it — the rooms left, the protection level, the demand and sell-up the recommender believes — frozen at issue time. Applying it authors a `rate_restriction` row through the same path a hand-posted restriction takes; a `lift` recommendation (the re-open) constrains nothing and its apply lifts the rows standing in its scope over its range, keeping them as history. The decision_* fields mutate exactly once on the transition out of `suggested`.", "operationId": "get_hospitality_restriction_recommendation_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.restriction_recommendation" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.restriction_recommendation:read" ] } ], "summary": "Read Restriction recommendation as of a watermark", "tags": [ "revenue_management" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.restriction_recommendation/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA typed sell-restriction recommendation issued by an agent against a scope (room type, rate plan, or the pair) over a date range: a closure, closed-to-arrival / departure, or a length-of- stay bound, with the reading that motivated it — the rooms left, the protection level, the demand and sell-up the recommender believes — frozen at issue time. Applying it authors a `rate_restriction` row through the same path a hand-posted restriction takes; a `lift` recommendation (the re-open) constrains nothing and its apply lifts the rows standing in its scope over its range, keeping them as history. The decision_* fields mutate exactly once on the transition out of `suggested`.", "operationId": "list_links_hospitality_restriction_recommendation", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.restriction_recommendation:read" ] } ], "summary": "List links of Restriction recommendation", "tags": [ "revenue_management" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.restriction_recommendation_applied_to_rate_restriction", "hospitality.link.restriction_recommendation_at_property", "hospitality.link.restriction_recommendation_for_rate_plan", "hospitality.link.restriction_recommendation_for_room_type", "hospitality.link.restriction_recommendation_lifted_rate_restriction", "hospitality.link.restriction_recommendation_part_of_run", "hospitality.link.restriction_recommendation_superseded_by", "hospitality.link.workflow_run_targets_restriction_recommendation" ] } } ] }, "/v1/object-types/hospitality.restriction_recommendation/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA typed sell-restriction recommendation issued by an agent against a scope (room type, rate plan, or the pair) over a date range: a closure, closed-to-arrival / departure, or a length-of- stay bound, with the reading that motivated it — the rooms left, the protection level, the demand and sell-up the recommender believes — frozen at issue time. Applying it authors a `rate_restriction` row through the same path a hand-posted restriction takes; a `lift` recommendation (the re-open) constrains nothing and its apply lifts the rows standing in its scope over its range, keeping them as history. The decision_* fields mutate exactly once on the transition out of `suggested`.", "operationId": "traverse_hospitality_restriction_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.restriction_recommendation_applied_to_rate_restriction", "hospitality.link.restriction_recommendation_at_property", "hospitality.link.restriction_recommendation_for_rate_plan", "hospitality.link.restriction_recommendation_for_room_type", "hospitality.link.restriction_recommendation_lifted_rate_restriction", "hospitality.link.restriction_recommendation_part_of_run", "hospitality.link.restriction_recommendation_superseded_by", "hospitality.link.workflow_run_targets_restriction_recommendation" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.restriction_recommendation:read" ] } ], "summary": "Traverse from Restriction recommendation", "tags": [ "revenue_management" ] } }, "/v1/object-types/hospitality.restriction_recommendation/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA typed sell-restriction recommendation issued by an agent against a scope (room type, rate plan, or the pair) over a date range: a closure, closed-to-arrival / departure, or a length-of- stay bound, with the reading that motivated it — the rooms left, the protection level, the demand and sell-up the recommender believes — frozen at issue time. Applying it authors a `rate_restriction` row through the same path a hand-posted restriction takes; a `lift` recommendation (the re-open) constrains nothing and its apply lifts the rows standing in its scope over its range, keeping them as history. The decision_* fields mutate exactly once on the transition out of `suggested`.", "operationId": "search_hospitality_restriction_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "start_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "start_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "start_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "end_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "end_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "end_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed_to_arrival" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "closed_to_departure" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "min_length_of_stay" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "min_length_of_stay" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "min_length_of_stay" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_length_of_stay" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_length_of_stay" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_length_of_stay" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "lift" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rooms_remaining" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rooms_remaining" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rooms_remaining" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "protection_level" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "protection_level" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "protection_level" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "demand_forecast_rooms" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "demand_forecast_rooms" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "demand_forecast_rooms" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sell_up_rate" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sell_up_rate" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sell_up_rate" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confidence" }, "type": { "const": "eq" }, "value": { "enum": [ "low", "medium", "high" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confidence_score" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confidence_score" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confidence_score" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "factors_considered" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "pickup_pace", "booking_curve", "competitive_set", "event_calendar", "historical_pattern", "segment_mix", "channel_mix", "length_of_stay_distribution", "cancellation_rate", "no_show_rate", "package_attachment", "group_displacement", "weather", "other" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rationale_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rationale_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "forecast_snapshot" }, "type": { "const": "eq" }, "value": { "properties": { "ari_score": { "format": "decimal", "type": "string" }, "as_of": { "format": "date-time", "type": "string" }, "competitive_set_adr": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "competitive_set_occupancy_pct": { "format": "decimal", "type": "string" }, "event_calendar_signal": { "type": "string" }, "forecast_kind": { "enum": [ "internal_pms", "external_rms", "external_str_compset", "hybrid", "other" ], "type": "string" }, "mpi_score": { "format": "decimal", "type": "string" }, "on_books_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "on_books_rooms": { "type": "integer" }, "pickup_last_24h": { "type": "integer" }, "pickup_last_7d": { "type": "integer" }, "rgi_score": { "format": "decimal", "type": "string" }, "transient_adr_forecast": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "transient_rooms_forecast": { "type": "integer" } }, "required": [ "forecast_kind", "as_of" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_on" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_on" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_on" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decision_status" }, "type": { "const": "eq" }, "value": { "enum": [ "suggested", "applied", "modified_and_applied", "rejected", "expired", "superseded" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejection_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejection_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "start_date", "end_date", "min_length_of_stay", "max_length_of_stay", "rooms_remaining", "protection_level", "demand_forecast_rooms", "sell_up_rate", "confidence", "confidence_score", "rationale_text", "issued_at", "expires_at", "expires_on", "decision_status", "decided_at", "rejection_reason" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.restriction_recommendation" }, "properties": { "additionalProperties": false, "properties": { "closed": { "title": "Hard stop-sell recommended", "type": "boolean" }, "closed_to_arrival": { "title": "Closed to arrival recommended", "type": "boolean" }, "closed_to_departure": { "title": "Closed to departure recommended", "type": "boolean" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Operator-facing confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Calibrated probability (0..=1) — set when the model emits one", "type": "string" }, "decided_at": { "format": "date-time", "title": "When the recommendation transitioned out of suggested", "type": "string" }, "decision_status": { "enum": [ "suggested", "applied", "modified_and_applied", "rejected", "expired", "superseded" ], "title": "Lifecycle state", "type": "string" }, "demand_forecast_rooms": { "format": "decimal", "title": "Unconstrained higher-rate demand the recommender believes for the first night, in rooms", "type": "string" }, "end_date": { "format": "date", "title": "Last night the restriction would cover (inclusive)", "type": "string" }, "expires_at": { "format": "date-time", "title": "After this, decision_status moves to expired", "type": "string" }, "expires_on": { "format": "date", "title": "The house business day this lapses after. When set, the house's open business date decides expiry (not the wall clock) and expires_at is the nominal end of that day in the house's timezone", "type": "string" }, "factors_considered": { "items": { "enum": [ "pickup_pace", "booking_curve", "competitive_set", "event_calendar", "historical_pattern", "segment_mix", "channel_mix", "length_of_stay_distribution", "cancellation_rate", "no_show_rate", "package_attachment", "group_displacement", "weather", "other" ], "type": "string" }, "title": "Signals the recommendation conditioned on (the strategy that fired)", "type": "array" }, "forecast_snapshot": { "description": "Forecast snapshot frozen at issue time (per §B.2)", "properties": { "ari_score": { "format": "decimal", "type": "string" }, "as_of": { "format": "date-time", "type": "string" }, "competitive_set_adr": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "competitive_set_occupancy_pct": { "format": "decimal", "type": "string" }, "event_calendar_signal": { "type": "string" }, "forecast_kind": { "enum": [ "internal_pms", "external_rms", "external_str_compset", "hybrid", "other" ], "type": "string" }, "mpi_score": { "format": "decimal", "type": "string" }, "on_books_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "on_books_rooms": { "type": "integer" }, "pickup_last_24h": { "type": "integer" }, "pickup_last_7d": { "type": "integer" }, "rgi_score": { "format": "decimal", "type": "string" }, "transient_adr_forecast": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "transient_rooms_forecast": { "type": "integer" } }, "required": [ "forecast_kind", "as_of" ], "title": "Restriction recommendation forecast snapshot", "type": "object" }, "id": { "title": "Recommendation id", "type": "string" }, "issued_at": { "format": "date-time", "title": "When the agent emitted the recommendation", "type": "string" }, "lift": { "title": "Recommend lifting what stands in the scope over the range (the re-open)", "type": "boolean" }, "max_length_of_stay": { "title": "Maximum length of stay recommended (nights)", "type": "integer" }, "min_length_of_stay": { "title": "Minimum length of stay recommended (nights)", "type": "integer" }, "protection_level": { "title": "Rooms the recommender wants kept for the higher rate (the protection level the restriction enforces)", "type": "integer" }, "rationale_text": { "title": "Human-readable explanation surfaced to operators", "type": "string" }, "rejection_reason": { "title": "Free-text reason set on reject", "type": "string" }, "rooms_remaining": { "title": "Rooms left to sell on the first night, at issue time", "type": "integer" }, "sell_up_rate": { "format": "decimal", "title": "Share of fenced-rate buyers believed to pay the higher rate once the fence closes (0..=1)", "type": "string" }, "start_date": { "format": "date", "title": "First night the restriction would cover", "type": "string" } }, "required": [ "id", "start_date", "end_date", "closed", "closed_to_arrival", "closed_to_departure", "confidence", "factors_considered", "issued_at", "expires_at", "decision_status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.restriction_recommendation:read" ] } ], "summary": "Search Restriction recommendation", "tags": [ "revenue_management" ] } }, "/v1/object-types/hospitality.retail_product/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA SKU-level retail product. Belongs to a retail_product_line and is available at venues / properties via M:N temporal links. Bridges to the venue POS catalogue via `service_item_is_retail_product` (a venue's POS may sell the same SKU as a catalogue item); the two surfaces overlap intentionally so the same physical SKU has one identity across DTC and in-venue channels.", "operationId": "get_hospitality_retail_product", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.retail_product" }, "properties": { "additionalProperties": false, "properties": { "barcode": { "title": "Barcode", "type": "string" }, "bundle_size": { "title": "Bundle size (multi-pack SKUs)", "type": "integer" }, "code": { "title": "SKU", "type": "string" }, "cost_amount": { "description": "Cost of goods (margin reporting)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Retail product cost amount", "type": "object" }, "cost_currency": { "format": "iso-4217", "title": "Cost currency (ISO 4217)", "type": "string" }, "currency": { "format": "iso-4217", "title": "Currency (ISO 4217)", "type": "string" }, "description": { "title": "Description", "type": "string" }, "image_url": { "title": "Image URL", "type": "string" }, "is_dtc_only": { "title": "DTC-only (no in-venue placement)", "type": "boolean" }, "kind": { "enum": [ "bath_body", "skincare", "fragrance", "candle", "home_goods", "wellness_consumable", "merchandise", "minibar_collab", "apparel", "other" ], "title": "Product kind (mirrors retail_product_line.kind)", "type": "string" }, "name": { "title": "Product name", "type": "string" }, "unit_price": { "description": "Unit price", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Retail product unit price", "type": "object" }, "volume_ml": { "title": "Volume (millilitres)", "type": "integer" }, "weight_grams": { "title": "Weight (grams)", "type": "integer" } }, "required": [ "code", "name", "kind", "unit_price", "currency", "is_dtc_only" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.retail_product:read" ] } ], "summary": "Read Retail product", "tags": [ "brand_venue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.retail_product/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA SKU-level retail product. Belongs to a retail_product_line and is available at venues / properties via M:N temporal links. Bridges to the venue POS catalogue via `service_item_is_retail_product` (a venue's POS may sell the same SKU as a catalogue item); the two surfaces overlap intentionally so the same physical SKU has one identity across DTC and in-venue channels.", "operationId": "get_hospitality_retail_product_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.retail_product" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.retail_product:read" ] } ], "summary": "Read Retail product as of a watermark", "tags": [ "brand_venue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.retail_product/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA SKU-level retail product. Belongs to a retail_product_line and is available at venues / properties via M:N temporal links. Bridges to the venue POS catalogue via `service_item_is_retail_product` (a venue's POS may sell the same SKU as a catalogue item); the two surfaces overlap intentionally so the same physical SKU has one identity across DTC and in-venue channels.", "operationId": "list_links_hospitality_retail_product", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.retail_product:read" ] } ], "summary": "List links of Retail product", "tags": [ "brand_venue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.retail_product_available_at_property", "hospitality.link.retail_product_available_at_venue", "hospitality.link.retail_product_belongs_to_line", "hospitality.link.service_item_is_retail_product" ] } } ] }, "/v1/object-types/hospitality.retail_product/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA SKU-level retail product. Belongs to a retail_product_line and is available at venues / properties via M:N temporal links. Bridges to the venue POS catalogue via `service_item_is_retail_product` (a venue's POS may sell the same SKU as a catalogue item); the two surfaces overlap intentionally so the same physical SKU has one identity across DTC and in-venue channels.", "operationId": "traverse_hospitality_retail_product", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.retail_product_available_at_property", "hospitality.link.retail_product_available_at_venue", "hospitality.link.retail_product_belongs_to_line", "hospitality.link.service_item_is_retail_product" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.retail_product:read" ] } ], "summary": "Traverse from Retail product", "tags": [ "brand_venue" ] } }, "/v1/object-types/hospitality.retail_product/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA SKU-level retail product. Belongs to a retail_product_line and is available at venues / properties via M:N temporal links. Bridges to the venue POS catalogue via `service_item_is_retail_product` (a venue's POS may sell the same SKU as a catalogue item); the two surfaces overlap intentionally so the same physical SKU has one identity across DTC and in-venue channels.", "operationId": "search_hospitality_retail_product", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "bath_body", "skincare", "fragrance", "candle", "home_goods", "wellness_consumable", "merchandise", "minibar_collab", "apparel", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "unit_price" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "currency" }, "type": { "const": "eq" }, "value": { "format": "iso-4217", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "weight_grams" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "weight_grams" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "weight_grams" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "volume_ml" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "volume_ml" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "volume_ml" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "image_url" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "image_url" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "image_url" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "image_url" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "barcode" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "barcode" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "barcode" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "barcode" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "bundle_size" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "bundle_size" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "bundle_size" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cost_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cost_currency" }, "type": { "const": "eq" }, "value": { "format": "iso-4217", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "is_dtc_only" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "kind", "description", "weight_grams", "volume_ml", "image_url", "barcode", "bundle_size" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.retail_product" }, "properties": { "additionalProperties": false, "properties": { "barcode": { "title": "Barcode", "type": "string" }, "bundle_size": { "title": "Bundle size (multi-pack SKUs)", "type": "integer" }, "code": { "title": "SKU", "type": "string" }, "cost_amount": { "description": "Cost of goods (margin reporting)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Retail product cost amount", "type": "object" }, "cost_currency": { "format": "iso-4217", "title": "Cost currency (ISO 4217)", "type": "string" }, "currency": { "format": "iso-4217", "title": "Currency (ISO 4217)", "type": "string" }, "description": { "title": "Description", "type": "string" }, "image_url": { "title": "Image URL", "type": "string" }, "is_dtc_only": { "title": "DTC-only (no in-venue placement)", "type": "boolean" }, "kind": { "enum": [ "bath_body", "skincare", "fragrance", "candle", "home_goods", "wellness_consumable", "merchandise", "minibar_collab", "apparel", "other" ], "title": "Product kind (mirrors retail_product_line.kind)", "type": "string" }, "name": { "title": "Product name", "type": "string" }, "unit_price": { "description": "Unit price", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Retail product unit price", "type": "object" }, "volume_ml": { "title": "Volume (millilitres)", "type": "integer" }, "weight_grams": { "title": "Weight (grams)", "type": "integer" } }, "required": [ "code", "name", "kind", "unit_price", "currency", "is_dtc_only" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.retail_product:read" ] } ], "summary": "Search Retail product", "tags": [ "brand_venue" ] } }, "/v1/object-types/hospitality.retail_product_line/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA brand-level catalogue of retail products — Cowshed-the-retail-line, Le Labo Santal 33, Edition × Le Labo amenities. Renamed from the pathway's `venue_retail_product_line` because the line is brand-level, not venue-bound — Cowshed exists at Soho House venues, at Liberty London, and at standalone Cowshed shops. Availability is a separate M:N link.", "operationId": "get_hospitality_retail_product_line", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.retail_product_line" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Retail product line code", "type": "string" }, "description": { "title": "Description", "type": "string" }, "kind": { "enum": [ "bath_body", "skincare", "fragrance", "candle", "home_goods", "wellness_consumable", "merchandise", "minibar_collab", "apparel", "other" ], "title": "Retail product line kind", "type": "string" }, "launched_on": { "format": "date", "title": "Launched on", "type": "string" }, "name": { "title": "Retail product line name", "type": "string" }, "partner_brand_text": { "title": "Co-brand partner (free-text; partners may not be Aerandil tenants)", "type": "string" }, "sunset_on": { "format": "date", "title": "Sunset on (null when current)", "type": "string" }, "website_url": { "title": "Website URL", "type": "string" } }, "required": [ "code", "name", "kind" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.retail_product_line:read" ] } ], "summary": "Read Retail product line", "tags": [ "brand_venue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.retail_product_line/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA brand-level catalogue of retail products — Cowshed-the-retail-line, Le Labo Santal 33, Edition × Le Labo amenities. Renamed from the pathway's `venue_retail_product_line` because the line is brand-level, not venue-bound — Cowshed exists at Soho House venues, at Liberty London, and at standalone Cowshed shops. Availability is a separate M:N link.", "operationId": "get_hospitality_retail_product_line_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.retail_product_line" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.retail_product_line:read" ] } ], "summary": "Read Retail product line as of a watermark", "tags": [ "brand_venue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.retail_product_line/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA brand-level catalogue of retail products — Cowshed-the-retail-line, Le Labo Santal 33, Edition × Le Labo amenities. Renamed from the pathway's `venue_retail_product_line` because the line is brand-level, not venue-bound — Cowshed exists at Soho House venues, at Liberty London, and at standalone Cowshed shops. Availability is a separate M:N link.", "operationId": "list_links_hospitality_retail_product_line", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.retail_product_line:read" ] } ], "summary": "List links of Retail product line", "tags": [ "brand_venue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.design_dna_has_signature_scent", "hospitality.link.retail_product_belongs_to_line", "hospitality.link.retail_product_line_has_brand_parent", "hospitality.link.retail_product_line_has_venue_brand_parent" ] } } ] }, "/v1/object-types/hospitality.retail_product_line/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA brand-level catalogue of retail products — Cowshed-the-retail-line, Le Labo Santal 33, Edition × Le Labo amenities. Renamed from the pathway's `venue_retail_product_line` because the line is brand-level, not venue-bound — Cowshed exists at Soho House venues, at Liberty London, and at standalone Cowshed shops. Availability is a separate M:N link.", "operationId": "traverse_hospitality_retail_product_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.design_dna_has_signature_scent", "hospitality.link.retail_product_belongs_to_line", "hospitality.link.retail_product_line_has_brand_parent", "hospitality.link.retail_product_line_has_venue_brand_parent" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.retail_product_line:read" ] } ], "summary": "Traverse from Retail product line", "tags": [ "brand_venue" ] } }, "/v1/object-types/hospitality.retail_product_line/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA brand-level catalogue of retail products — Cowshed-the-retail-line, Le Labo Santal 33, Edition × Le Labo amenities. Renamed from the pathway's `venue_retail_product_line` because the line is brand-level, not venue-bound — Cowshed exists at Soho House venues, at Liberty London, and at standalone Cowshed shops. Availability is a separate M:N link.", "operationId": "search_hospitality_retail_product_line", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "bath_body", "skincare", "fragrance", "candle", "home_goods", "wellness_consumable", "merchandise", "minibar_collab", "apparel", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "partner_brand_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "partner_brand_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "partner_brand_text" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "partner_brand_text" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "launched_on" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "launched_on" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "launched_on" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sunset_on" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sunset_on" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sunset_on" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "website_url" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "website_url" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "website_url" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "website_url" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "kind", "partner_brand_text", "launched_on", "sunset_on", "description", "website_url" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.retail_product_line" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Retail product line code", "type": "string" }, "description": { "title": "Description", "type": "string" }, "kind": { "enum": [ "bath_body", "skincare", "fragrance", "candle", "home_goods", "wellness_consumable", "merchandise", "minibar_collab", "apparel", "other" ], "title": "Retail product line kind", "type": "string" }, "launched_on": { "format": "date", "title": "Launched on", "type": "string" }, "name": { "title": "Retail product line name", "type": "string" }, "partner_brand_text": { "title": "Co-brand partner (free-text; partners may not be Aerandil tenants)", "type": "string" }, "sunset_on": { "format": "date", "title": "Sunset on (null when current)", "type": "string" }, "website_url": { "title": "Website URL", "type": "string" } }, "required": [ "code", "name", "kind" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.retail_product_line:read" ] } ], "summary": "Search Retail product line", "tags": [ "brand_venue" ] } }, "/v1/object-types/hospitality.room/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA physical room. Rooms always belong to a property and are linked to a room type. State is three orthogonal axes: housekeeping_status (the cleaning axis), occupancy (system truth, written by check-in / check-out / room moves), and the attendant-observed occupancy pair whose disagreement with system occupancy derives a room_discrepancy. Out-of-order / out-of-service are dated room_status_block records, not statuses here.", "operationId": "get_hospitality_room", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" }, "properties": { "additionalProperties": false, "properties": { "bed_configuration": { "enum": [ "joined", "split" ], "title": "How the room's convertible beds are made up now: joined (one double or king) or split (two singles); absent when they do not convert or nobody recorded it", "type": "string" }, "code": { "title": "Vendor-alignment room code (tenant-unique; connector mappings resolve by it)", "type": "string" }, "connecting_to": { "title": "Connecting to room number", "type": "string" }, "features": { "items": { "type": "string" }, "title": "Features", "type": "array" }, "floor": { "title": "Floor", "type": "string" }, "housekeeping_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Housekeeping status (cleaning axis)", "type": "string" }, "number": { "title": "Room number", "type": "string" }, "observed_at": { "format": "date-time", "title": "When the observation was reported", "type": "string" }, "observed_occupancy": { "enum": [ "vacant", "occupied" ], "title": "Attendant-observed occupancy (discrepancy comparator)", "type": "string" }, "observed_persons": { "title": "Attendant-observed occupant count", "type": "integer" }, "occupancy": { "enum": [ "vacant", "occupied" ], "title": "System occupancy (front-office truth)", "type": "string" }, "reader_code": { "title": "The code the room's QR / NFC reader carries (unique within the property)", "type": "string" } }, "required": [ "number", "housekeeping_status", "occupancy" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.room:read" ] } ], "summary": "Read Room", "tags": [ "inventory" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.room/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA physical room. Rooms always belong to a property and are linked to a room type. State is three orthogonal axes: housekeeping_status (the cleaning axis), occupancy (system truth, written by check-in / check-out / room moves), and the attendant-observed occupancy pair whose disagreement with system occupancy derives a room_discrepancy. Out-of-order / out-of-service are dated room_status_block records, not statuses here.", "operationId": "get_hospitality_room_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.room" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.room:read" ] } ], "summary": "Read Room as of a watermark", "tags": [ "inventory" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.room/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA physical room. Rooms always belong to a property and are linked to a room type. State is three orthogonal axes: housekeeping_status (the cleaning axis), occupancy (system truth, written by check-in / check-out / room moves), and the attendant-observed occupancy pair whose disagreement with system occupancy derives a room_discrepancy. Out-of-order / out-of-service are dated room_status_block records, not statuses here.", "operationId": "list_links_hospitality_room", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.room:read" ] } ], "summary": "List links of Room", "tags": [ "inventory" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.asset_in_room", "hospitality.link.checkpoint_result_for_room", "hospitality.link.housekeeping_task_for_room", "hospitality.link.lost_found_item_in_room", "hospitality.link.maintenance_plan_for_room", "hospitality.link.pattern_at_room", "hospitality.link.property_has_room", "hospitality.link.reservation_room_assigned_to", "hospitality.link.room_discrepancy_for_room", "hospitality.link.room_status_block_for_room", "hospitality.link.room_type_has_room", "hospitality.link.stay_in_room", "hospitality.link.stock_movement_for_room", "hospitality.link.stock_store_in_room", "hospitality.link.stored_object_for_room", "hospitality.link.work_order_for_room", "hospitality.link.workflow_run_targets_room" ] } } ] }, "/v1/object-types/hospitality.room/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA physical room. Rooms always belong to a property and are linked to a room type. State is three orthogonal axes: housekeeping_status (the cleaning axis), occupancy (system truth, written by check-in / check-out / room moves), and the attendant-observed occupancy pair whose disagreement with system occupancy derives a room_discrepancy. Out-of-order / out-of-service are dated room_status_block records, not statuses here.", "operationId": "traverse_hospitality_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.asset_in_room", "hospitality.link.checkpoint_result_for_room", "hospitality.link.housekeeping_task_for_room", "hospitality.link.lost_found_item_in_room", "hospitality.link.maintenance_plan_for_room", "hospitality.link.pattern_at_room", "hospitality.link.property_has_room", "hospitality.link.reservation_room_assigned_to", "hospitality.link.room_discrepancy_for_room", "hospitality.link.room_status_block_for_room", "hospitality.link.room_type_has_room", "hospitality.link.stay_in_room", "hospitality.link.stock_movement_for_room", "hospitality.link.stock_store_in_room", "hospitality.link.stored_object_for_room", "hospitality.link.work_order_for_room", "hospitality.link.workflow_run_targets_room" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.room:read" ] } ], "summary": "Traverse from Room", "tags": [ "inventory" ] } }, "/v1/object-types/hospitality.room/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA physical room. Rooms always belong to a property and are linked to a room type. State is three orthogonal axes: housekeeping_status (the cleaning axis), occupancy (system truth, written by check-in / check-out / room moves), and the attendant-observed occupancy pair whose disagreement with system occupancy derives a room_discrepancy. Out-of-order / out-of-service are dated room_status_block records, not statuses here.", "operationId": "search_hospitality_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "number" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "number" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "number" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "number" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "floor" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "floor" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "floor" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "floor" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "housekeeping_status" }, "type": { "const": "eq" }, "value": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "occupancy" }, "type": { "const": "eq" }, "value": { "enum": [ "vacant", "occupied" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "observed_occupancy" }, "type": { "const": "eq" }, "value": { "enum": [ "vacant", "occupied" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "observed_persons" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "observed_persons" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "observed_persons" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "observed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "observed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "observed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "connecting_to" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "connecting_to" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "connecting_to" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "connecting_to" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "features" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reader_code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reader_code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reader_code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reader_code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "bed_configuration" }, "type": { "const": "eq" }, "value": { "enum": [ "joined", "split" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "number", "floor", "housekeeping_status", "occupancy", "observed_occupancy", "observed_persons", "observed_at", "connecting_to", "code", "reader_code", "bed_configuration" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room" }, "properties": { "additionalProperties": false, "properties": { "bed_configuration": { "enum": [ "joined", "split" ], "title": "How the room's convertible beds are made up now: joined (one double or king) or split (two singles); absent when they do not convert or nobody recorded it", "type": "string" }, "code": { "title": "Vendor-alignment room code (tenant-unique; connector mappings resolve by it)", "type": "string" }, "connecting_to": { "title": "Connecting to room number", "type": "string" }, "features": { "items": { "type": "string" }, "title": "Features", "type": "array" }, "floor": { "title": "Floor", "type": "string" }, "housekeeping_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Housekeeping status (cleaning axis)", "type": "string" }, "number": { "title": "Room number", "type": "string" }, "observed_at": { "format": "date-time", "title": "When the observation was reported", "type": "string" }, "observed_occupancy": { "enum": [ "vacant", "occupied" ], "title": "Attendant-observed occupancy (discrepancy comparator)", "type": "string" }, "observed_persons": { "title": "Attendant-observed occupant count", "type": "integer" }, "occupancy": { "enum": [ "vacant", "occupied" ], "title": "System occupancy (front-office truth)", "type": "string" }, "reader_code": { "title": "The code the room's QR / NFC reader carries (unique within the property)", "type": "string" } }, "required": [ "number", "housekeeping_status", "occupancy" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.room:read" ] } ], "summary": "Search Room", "tags": [ "inventory" ] } }, "/v1/object-types/hospitality.room_discrepancy/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA derived disagreement between system occupancy and what the attendant physically found (OPERA's skip / sleep / person model, plus the resolution audit it lacks): `skip` — system occupied, found vacant; `sleep` — system vacant, found occupied; `person` — occupant count mismatch. Raised and auto-resolved by set_room_housekeeping_status when the views diverge and re-agree; front-desk verdicts land through resolve_room_discrepancy with a typed outcome, so every discrepancy closes with a recorded why.", "operationId": "get_hospitality_room_discrepancy", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room_discrepancy" }, "properties": { "additionalProperties": false, "properties": { "expected_persons": { "title": "Occupants per the in-house reservation", "type": "integer" }, "id": { "title": "Discrepancy id", "type": "string" }, "kind": { "enum": [ "skip", "sleep", "person" ], "title": "Discrepancy kind", "type": "string" }, "notes": { "title": "Resolution notes", "type": "string" }, "observed_occupancy": { "enum": [ "vacant", "occupied" ], "title": "Observed occupancy at raise time", "type": "string" }, "observed_persons": { "title": "Occupants the attendant counted", "type": "integer" }, "outcome": { "enum": [ "statuses_realigned", "walkout_confirmed", "unregistered_occupant_registered", "observation_error", "corrected_by_front_office" ], "title": "How the investigation closed", "type": "string" }, "raised_at": { "format": "date-time", "title": "Raised at", "type": "string" }, "resolved_at": { "format": "date-time", "title": "Resolved at", "type": "string" }, "status": { "enum": [ "open", "resolved" ], "title": "Status", "type": "string" }, "system_occupancy": { "enum": [ "vacant", "occupied" ], "title": "System occupancy at raise time", "type": "string" } }, "required": [ "id", "kind", "status", "system_occupancy", "observed_occupancy", "raised_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.room_discrepancy:read" ] } ], "summary": "Read Room discrepancy", "tags": [ "inventory" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.room_discrepancy/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA derived disagreement between system occupancy and what the attendant physically found (OPERA's skip / sleep / person model, plus the resolution audit it lacks): `skip` — system occupied, found vacant; `sleep` — system vacant, found occupied; `person` — occupant count mismatch. Raised and auto-resolved by set_room_housekeeping_status when the views diverge and re-agree; front-desk verdicts land through resolve_room_discrepancy with a typed outcome, so every discrepancy closes with a recorded why.", "operationId": "get_hospitality_room_discrepancy_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.room_discrepancy" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.room_discrepancy:read" ] } ], "summary": "Read Room discrepancy as of a watermark", "tags": [ "inventory" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.room_discrepancy/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA derived disagreement between system occupancy and what the attendant physically found (OPERA's skip / sleep / person model, plus the resolution audit it lacks): `skip` — system occupied, found vacant; `sleep` — system vacant, found occupied; `person` — occupant count mismatch. Raised and auto-resolved by set_room_housekeeping_status when the views diverge and re-agree; front-desk verdicts land through resolve_room_discrepancy with a typed outcome, so every discrepancy closes with a recorded why.", "operationId": "list_links_hospitality_room_discrepancy", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.room_discrepancy:read" ] } ], "summary": "List links of Room discrepancy", "tags": [ "inventory" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.room_discrepancy_for_room" ] } } ] }, "/v1/object-types/hospitality.room_discrepancy/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA derived disagreement between system occupancy and what the attendant physically found (OPERA's skip / sleep / person model, plus the resolution audit it lacks): `skip` — system occupied, found vacant; `sleep` — system vacant, found occupied; `person` — occupant count mismatch. Raised and auto-resolved by set_room_housekeeping_status when the views diverge and re-agree; front-desk verdicts land through resolve_room_discrepancy with a typed outcome, so every discrepancy closes with a recorded why.", "operationId": "traverse_hospitality_room_discrepancy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.room_discrepancy_for_room" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.room_discrepancy:read" ] } ], "summary": "Traverse from Room discrepancy", "tags": [ "inventory" ] } }, "/v1/object-types/hospitality.room_discrepancy/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA derived disagreement between system occupancy and what the attendant physically found (OPERA's skip / sleep / person model, plus the resolution audit it lacks): `skip` — system occupied, found vacant; `sleep` — system vacant, found occupied; `person` — occupant count mismatch. Raised and auto-resolved by set_room_housekeeping_status when the views diverge and re-agree; front-desk verdicts land through resolve_room_discrepancy with a typed outcome, so every discrepancy closes with a recorded why.", "operationId": "search_hospitality_room_discrepancy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "skip", "sleep", "person" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "open", "resolved" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "system_occupancy" }, "type": { "const": "eq" }, "value": { "enum": [ "vacant", "occupied" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "observed_occupancy" }, "type": { "const": "eq" }, "value": { "enum": [ "vacant", "occupied" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expected_persons" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expected_persons" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expected_persons" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "observed_persons" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "observed_persons" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "observed_persons" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "raised_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "raised_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "raised_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "resolved_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "resolved_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "resolved_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "outcome" }, "type": { "const": "eq" }, "value": { "enum": [ "statuses_realigned", "walkout_confirmed", "unregistered_occupant_registered", "observation_error", "corrected_by_front_office" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "kind", "status", "system_occupancy", "observed_occupancy", "expected_persons", "observed_persons", "raised_at", "resolved_at", "outcome", "notes" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room_discrepancy" }, "properties": { "additionalProperties": false, "properties": { "expected_persons": { "title": "Occupants per the in-house reservation", "type": "integer" }, "id": { "title": "Discrepancy id", "type": "string" }, "kind": { "enum": [ "skip", "sleep", "person" ], "title": "Discrepancy kind", "type": "string" }, "notes": { "title": "Resolution notes", "type": "string" }, "observed_occupancy": { "enum": [ "vacant", "occupied" ], "title": "Observed occupancy at raise time", "type": "string" }, "observed_persons": { "title": "Occupants the attendant counted", "type": "integer" }, "outcome": { "enum": [ "statuses_realigned", "walkout_confirmed", "unregistered_occupant_registered", "observation_error", "corrected_by_front_office" ], "title": "How the investigation closed", "type": "string" }, "raised_at": { "format": "date-time", "title": "Raised at", "type": "string" }, "resolved_at": { "format": "date-time", "title": "Resolved at", "type": "string" }, "status": { "enum": [ "open", "resolved" ], "title": "Status", "type": "string" }, "system_occupancy": { "enum": [ "vacant", "occupied" ], "title": "System occupancy at raise time", "type": "string" } }, "required": [ "id", "kind", "status", "system_occupancy", "observed_occupancy", "raised_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.room_discrepancy:read" ] } ], "summary": "Search Room discrepancy", "tags": [ "inventory" ] } }, "/v1/object-types/hospitality.room_queue_entry/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA reservation waiting at the desk for its room to turn — OPERA's queue room as a first-class object. Created by `queue_reservation_for_room` (which also rush-bumps the assigned room's open housekeeping task to urgent), fulfilled by `check_in` itself the moment the guest gets the room, or cancelled by the desk. Carries no manual priority: urgency derives from the reservation (arrival time, wait duration) and the rush signal lives on the task, so an agent working the queue reads state instead of maintaining a second copy of it.", "operationId": "get_hospitality_room_queue_entry", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room_queue_entry" }, "properties": { "additionalProperties": false, "properties": { "cancel_reason": { "title": "Why the wait was withdrawn", "type": "string" }, "cancelled_at": { "format": "date-time", "title": "When the desk withdrew the wait", "type": "string" }, "fulfilled_at": { "format": "date-time", "title": "When check-in handed the guest the room", "type": "string" }, "id": { "title": "Queue entry id", "type": "string" }, "notes": { "title": "Desk notes (where the guest is waiting, luggage)", "type": "string" }, "queued_at": { "format": "date-time", "title": "When the guest joined the queue", "type": "string" }, "status": { "enum": [ "waiting", "fulfilled", "cancelled" ], "title": "Status", "type": "string" } }, "required": [ "id", "status", "queued_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.room_queue_entry:read" ] } ], "summary": "Read Room queue entry", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.room_queue_entry/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA reservation waiting at the desk for its room to turn — OPERA's queue room as a first-class object. Created by `queue_reservation_for_room` (which also rush-bumps the assigned room's open housekeeping task to urgent), fulfilled by `check_in` itself the moment the guest gets the room, or cancelled by the desk. Carries no manual priority: urgency derives from the reservation (arrival time, wait duration) and the rush signal lives on the task, so an agent working the queue reads state instead of maintaining a second copy of it.", "operationId": "get_hospitality_room_queue_entry_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.room_queue_entry" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.room_queue_entry:read" ] } ], "summary": "Read Room queue entry as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.room_queue_entry/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA reservation waiting at the desk for its room to turn — OPERA's queue room as a first-class object. Created by `queue_reservation_for_room` (which also rush-bumps the assigned room's open housekeeping task to urgent), fulfilled by `check_in` itself the moment the guest gets the room, or cancelled by the desk. Carries no manual priority: urgency derives from the reservation (arrival time, wait duration) and the rush signal lives on the task, so an agent working the queue reads state instead of maintaining a second copy of it.", "operationId": "list_links_hospitality_room_queue_entry", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.room_queue_entry:read" ] } ], "summary": "List links of Room queue entry", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.room_queue_entry_for_reservation" ] } } ] }, "/v1/object-types/hospitality.room_queue_entry/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA reservation waiting at the desk for its room to turn — OPERA's queue room as a first-class object. Created by `queue_reservation_for_room` (which also rush-bumps the assigned room's open housekeeping task to urgent), fulfilled by `check_in` itself the moment the guest gets the room, or cancelled by the desk. Carries no manual priority: urgency derives from the reservation (arrival time, wait duration) and the rush signal lives on the task, so an agent working the queue reads state instead of maintaining a second copy of it.", "operationId": "traverse_hospitality_room_queue_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.room_queue_entry_for_reservation" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.room_queue_entry:read" ] } ], "summary": "Traverse from Room queue entry", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.room_queue_entry/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA reservation waiting at the desk for its room to turn — OPERA's queue room as a first-class object. Created by `queue_reservation_for_room` (which also rush-bumps the assigned room's open housekeeping task to urgent), fulfilled by `check_in` itself the moment the guest gets the room, or cancelled by the desk. Carries no manual priority: urgency derives from the reservation (arrival time, wait duration) and the rush signal lives on the task, so an agent working the queue reads state instead of maintaining a second copy of it.", "operationId": "search_hospitality_room_queue_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "waiting", "fulfilled", "cancelled" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "queued_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "queued_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "queued_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fulfilled_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fulfilled_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fulfilled_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancelled_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancelled_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancelled_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancel_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancel_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "status", "queued_at", "fulfilled_at", "cancelled_at", "cancel_reason", "notes" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room_queue_entry" }, "properties": { "additionalProperties": false, "properties": { "cancel_reason": { "title": "Why the wait was withdrawn", "type": "string" }, "cancelled_at": { "format": "date-time", "title": "When the desk withdrew the wait", "type": "string" }, "fulfilled_at": { "format": "date-time", "title": "When check-in handed the guest the room", "type": "string" }, "id": { "title": "Queue entry id", "type": "string" }, "notes": { "title": "Desk notes (where the guest is waiting, luggage)", "type": "string" }, "queued_at": { "format": "date-time", "title": "When the guest joined the queue", "type": "string" }, "status": { "enum": [ "waiting", "fulfilled", "cancelled" ], "title": "Status", "type": "string" } }, "required": [ "id", "status", "queued_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.room_queue_entry:read" ] } ], "summary": "Search Room queue entry", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.room_status_block/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA dated out-of-order or out-of-service record against one room — the time-boxed inventory fact OPERA and Mews both model underneath their status enums. `out_of_order` deducts the blocked dates from the room type's sellable inventory (availability_day.out_of_order) and refuses assignment; `out_of_service` is an advisory flag with no inventory effect. `return_status` names the housekeeping status the room re-enters on release — declared at creation, so a block can never expire into an undefined state. `ledger_dates` records exactly which availability rows the block decremented (release restores exactly those); `displaced_dates` records nights where the deduction pushed sold past the new ceiling — overbooking exposure reported, never silently absorbed.", "operationId": "get_hospitality_room_status_block", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room_status_block" }, "properties": { "additionalProperties": false, "properties": { "blocked_at": { "format": "date-time", "title": "When the block was recorded", "type": "string" }, "displaced_dates": { "items": { "format": "date", "type": "string" }, "title": "Blocked dates already sold past the reduced ceiling", "type": "array" }, "end_date": { "format": "date", "title": "Last blocked night (inclusive through-date)", "type": "string" }, "id": { "title": "Block id", "type": "string" }, "kind": { "enum": [ "out_of_order", "out_of_service" ], "title": "Block kind", "type": "string" }, "ledger_dates": { "items": { "format": "date", "type": "string" }, "title": "Dates whose availability rows this block decremented", "type": "array" }, "reason": { "title": "Reason", "type": "string" }, "released_at": { "format": "date-time", "title": "When the block was released", "type": "string" }, "remarks": { "title": "Remarks", "type": "string" }, "return_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Housekeeping status the room re-enters on release", "type": "string" }, "start_date": { "format": "date", "title": "First blocked night", "type": "string" }, "status": { "enum": [ "active", "released" ], "title": "Status", "type": "string" } }, "required": [ "id", "kind", "status", "start_date", "end_date", "reason", "return_status", "blocked_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.room_status_block:read" ] } ], "summary": "Read Room status block", "tags": [ "inventory" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.room_status_block/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA dated out-of-order or out-of-service record against one room — the time-boxed inventory fact OPERA and Mews both model underneath their status enums. `out_of_order` deducts the blocked dates from the room type's sellable inventory (availability_day.out_of_order) and refuses assignment; `out_of_service` is an advisory flag with no inventory effect. `return_status` names the housekeeping status the room re-enters on release — declared at creation, so a block can never expire into an undefined state. `ledger_dates` records exactly which availability rows the block decremented (release restores exactly those); `displaced_dates` records nights where the deduction pushed sold past the new ceiling — overbooking exposure reported, never silently absorbed.", "operationId": "get_hospitality_room_status_block_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.room_status_block" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.room_status_block:read" ] } ], "summary": "Read Room status block as of a watermark", "tags": [ "inventory" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.room_status_block/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA dated out-of-order or out-of-service record against one room — the time-boxed inventory fact OPERA and Mews both model underneath their status enums. `out_of_order` deducts the blocked dates from the room type's sellable inventory (availability_day.out_of_order) and refuses assignment; `out_of_service` is an advisory flag with no inventory effect. `return_status` names the housekeeping status the room re-enters on release — declared at creation, so a block can never expire into an undefined state. `ledger_dates` records exactly which availability rows the block decremented (release restores exactly those); `displaced_dates` records nights where the deduction pushed sold past the new ceiling — overbooking exposure reported, never silently absorbed.", "operationId": "list_links_hospitality_room_status_block", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.room_status_block:read" ] } ], "summary": "List links of Room status block", "tags": [ "inventory" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.room_status_block_for_room", "hospitality.link.work_order_holds_block" ] } } ] }, "/v1/object-types/hospitality.room_status_block/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA dated out-of-order or out-of-service record against one room — the time-boxed inventory fact OPERA and Mews both model underneath their status enums. `out_of_order` deducts the blocked dates from the room type's sellable inventory (availability_day.out_of_order) and refuses assignment; `out_of_service` is an advisory flag with no inventory effect. `return_status` names the housekeeping status the room re-enters on release — declared at creation, so a block can never expire into an undefined state. `ledger_dates` records exactly which availability rows the block decremented (release restores exactly those); `displaced_dates` records nights where the deduction pushed sold past the new ceiling — overbooking exposure reported, never silently absorbed.", "operationId": "traverse_hospitality_room_status_block", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.room_status_block_for_room", "hospitality.link.work_order_holds_block" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.room_status_block:read" ] } ], "summary": "Traverse from Room status block", "tags": [ "inventory" ] } }, "/v1/object-types/hospitality.room_status_block/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA dated out-of-order or out-of-service record against one room — the time-boxed inventory fact OPERA and Mews both model underneath their status enums. `out_of_order` deducts the blocked dates from the room type's sellable inventory (availability_day.out_of_order) and refuses assignment; `out_of_service` is an advisory flag with no inventory effect. `return_status` names the housekeeping status the room re-enters on release — declared at creation, so a block can never expire into an undefined state. `ledger_dates` records exactly which availability rows the block decremented (release restores exactly those); `displaced_dates` records nights where the deduction pushed sold past the new ceiling — overbooking exposure reported, never silently absorbed.", "operationId": "search_hospitality_room_status_block", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "out_of_order", "out_of_service" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "released" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "start_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "start_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "start_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "end_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "end_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "end_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reason" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reason" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "remarks" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "remarks" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "return_status" }, "type": { "const": "eq" }, "value": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "blocked_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "blocked_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "blocked_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "released_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "released_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "released_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ledger_dates" }, "type": { "const": "eq" }, "value": { "items": { "format": "date", "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "displaced_dates" }, "type": { "const": "eq" }, "value": { "items": { "format": "date", "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "kind", "status", "start_date", "end_date", "reason", "remarks", "return_status", "blocked_at", "released_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room_status_block" }, "properties": { "additionalProperties": false, "properties": { "blocked_at": { "format": "date-time", "title": "When the block was recorded", "type": "string" }, "displaced_dates": { "items": { "format": "date", "type": "string" }, "title": "Blocked dates already sold past the reduced ceiling", "type": "array" }, "end_date": { "format": "date", "title": "Last blocked night (inclusive through-date)", "type": "string" }, "id": { "title": "Block id", "type": "string" }, "kind": { "enum": [ "out_of_order", "out_of_service" ], "title": "Block kind", "type": "string" }, "ledger_dates": { "items": { "format": "date", "type": "string" }, "title": "Dates whose availability rows this block decremented", "type": "array" }, "reason": { "title": "Reason", "type": "string" }, "released_at": { "format": "date-time", "title": "When the block was released", "type": "string" }, "remarks": { "title": "Remarks", "type": "string" }, "return_status": { "enum": [ "dirty", "pickup", "clean", "inspected" ], "title": "Housekeeping status the room re-enters on release", "type": "string" }, "start_date": { "format": "date", "title": "First blocked night", "type": "string" }, "status": { "enum": [ "active", "released" ], "title": "Status", "type": "string" } }, "required": [ "id", "kind", "status", "start_date", "end_date", "reason", "return_status", "blocked_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.room_status_block:read" ] } ], "summary": "Search Room status block", "tags": [ "inventory" ] } }, "/v1/object-types/hospitality.room_type/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA category of rooms sharing layout, rate, and amenities. Reservations are typically booked against a room type and only assigned to a specific room at check-in.", "operationId": "get_hospitality_room_type", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room_type" }, "properties": { "additionalProperties": false, "properties": { "amenities": { "items": { "type": "string" }, "title": "Amenities", "type": "array" }, "base_rate": { "description": "Base rate", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Room Type base rate", "type": "object" }, "bed_configuration": { "title": "Bed configuration", "type": "string" }, "code": { "title": "Room type code", "type": "string" }, "description": { "title": "Description", "type": "string" }, "max_occupancy": { "title": "Max occupancy", "type": "integer" }, "name": { "title": "Room type name", "type": "string" }, "size_sqm": { "format": "decimal", "title": "Size (m²)", "type": "string" }, "view": { "enum": [ "city", "ocean", "garden", "pool", "mountain", "courtyard", "interior", "none" ], "title": "View", "type": "string" } }, "required": [ "code", "name", "max_occupancy" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.room_type:read" ] } ], "summary": "Read Room Type", "tags": [ "inventory" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.room_type/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA category of rooms sharing layout, rate, and amenities. Reservations are typically booked against a room type and only assigned to a specific room at check-in.", "operationId": "get_hospitality_room_type_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.room_type" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.room_type:read" ] } ], "summary": "Read Room Type as of a watermark", "tags": [ "inventory" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.room_type/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA category of rooms sharing layout, rate, and amenities. Reservations are typically booked against a room type and only assigned to a specific room at check-in.", "operationId": "list_links_hospitality_room_type", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.room_type:read" ] } ], "summary": "List links of Room Type", "tags": [ "inventory" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.block_allocation_for_room_type", "hospitality.link.channel_mapping_for_room_type", "hospitality.link.checklist_template_for_room_type", "hospitality.link.derived_rate_for_room_type", "hospitality.link.property_has_room_type", "hospitality.link.recommendation_for_room_type", "hospitality.link.reservation_for_room_type", "hospitality.link.reservation_room_charged_as_room_type", "hospitality.link.reservation_room_for_room_type", "hospitality.link.restriction_recommendation_for_room_type", "hospitality.link.room_type_has_availability_day", "hospitality.link.room_type_has_rate_per_night", "hospitality.link.room_type_has_restriction", "hospitality.link.room_type_has_room", "hospitality.link.sell_limit_recommendation_for_room_type", "hospitality.link.stay_offer_for_room_type", "hospitality.link.turnaway_for_room_type", "hospitality.link.waitlist_entry_for_room_type" ] } } ] }, "/v1/object-types/hospitality.room_type/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA category of rooms sharing layout, rate, and amenities. Reservations are typically booked against a room type and only assigned to a specific room at check-in.", "operationId": "traverse_hospitality_room_type", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.block_allocation_for_room_type", "hospitality.link.channel_mapping_for_room_type", "hospitality.link.checklist_template_for_room_type", "hospitality.link.derived_rate_for_room_type", "hospitality.link.property_has_room_type", "hospitality.link.recommendation_for_room_type", "hospitality.link.reservation_for_room_type", "hospitality.link.reservation_room_charged_as_room_type", "hospitality.link.reservation_room_for_room_type", "hospitality.link.restriction_recommendation_for_room_type", "hospitality.link.room_type_has_availability_day", "hospitality.link.room_type_has_rate_per_night", "hospitality.link.room_type_has_restriction", "hospitality.link.room_type_has_room", "hospitality.link.sell_limit_recommendation_for_room_type", "hospitality.link.stay_offer_for_room_type", "hospitality.link.turnaway_for_room_type", "hospitality.link.waitlist_entry_for_room_type" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.room_type:read" ] } ], "summary": "Traverse from Room Type", "tags": [ "inventory" ] } }, "/v1/object-types/hospitality.room_type/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA category of rooms sharing layout, rate, and amenities. Reservations are typically booked against a room type and only assigned to a specific room at check-in.", "operationId": "search_hospitality_room_type", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_occupancy" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_occupancy" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_occupancy" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "base_rate" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "amenities" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "view" }, "type": { "const": "eq" }, "value": { "enum": [ "city", "ocean", "garden", "pool", "mountain", "courtyard", "interior", "none" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "bed_configuration" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "bed_configuration" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "bed_configuration" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "bed_configuration" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "size_sqm" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "size_sqm" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "size_sqm" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "description", "max_occupancy", "view", "bed_configuration", "size_sqm" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.room_type" }, "properties": { "additionalProperties": false, "properties": { "amenities": { "items": { "type": "string" }, "title": "Amenities", "type": "array" }, "base_rate": { "description": "Base rate", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Room Type base rate", "type": "object" }, "bed_configuration": { "title": "Bed configuration", "type": "string" }, "code": { "title": "Room type code", "type": "string" }, "description": { "title": "Description", "type": "string" }, "max_occupancy": { "title": "Max occupancy", "type": "integer" }, "name": { "title": "Room type name", "type": "string" }, "size_sqm": { "format": "decimal", "title": "Size (m²)", "type": "string" }, "view": { "enum": [ "city", "ocean", "garden", "pool", "mountain", "courtyard", "interior", "none" ], "title": "View", "type": "string" } }, "required": [ "code", "name", "max_occupancy" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.room_type:read" ] } ], "summary": "Search Room Type", "tags": [ "inventory" ] } }, "/v1/object-types/hospitality.round_template/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA house's planned walk — hubOS's revision structure: a name, a `family` (corrective, preventive, technical_legal, inspection_legal), the maintenance plan's cadence (`fixed` to the calendar or `floating` from the last completion, every `interval_days`) and its next due date, and the `checkpoints` in order — each a room or a piece of equipment of this house (`ref_id`), or a general place named by its `label`, with the items checked there (`check`, `reading` with its unit and optional `min` / `max`, `text`, `photo`, and `section` headings). One active template per house and name: defining the name again revises it in place. The automation lane is its clock: a sweep over active templates whose due instant has come (`next_due_at`, the house's midnight starting `next_due_on`) and that have no round open starts one (`start_inspection_round`); completing the round moves `next_due_on` on. `open_round_id` names the round in progress; `revision` counts the walks it has defined (a re-definition that moves the checkpoints is the next), and a start may name the one it saw.", "operationId": "get_hospitality_round_template", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.round_template" }, "properties": { "additionalProperties": false, "properties": { "cadence": { "enum": [ "fixed", "floating" ], "title": "Fixed to the calendar, or floating from the last completion", "type": "string" }, "checkpoints": { "description": "The checkpoints, in walking order, each with its items", "items": { "properties": { "items": { "items": { "properties": { "code": { "type": "string" }, "kind": { "enum": [ "check", "reading", "text", "photo", "section" ], "type": "string" }, "label": { "type": "string" }, "max": { "format": "decimal", "type": "string" }, "min": { "format": "decimal", "type": "string" }, "unit": { "type": "string" } }, "required": [ "code", "label", "kind" ], "type": "object" }, "type": "array" }, "kind": { "enum": [ "room", "asset", "general" ], "type": "string" }, "label": { "type": "string" }, "position": { "type": "integer" }, "ref_id": { "type": "string" } }, "required": [ "position", "kind", "items" ], "type": "object" }, "title": "Round template checkpoints", "type": "array" }, "description": { "title": "What the walk is for, in words", "type": "string" }, "family": { "enum": [ "corrective", "preventive", "technical_legal", "inspection_legal" ], "title": "corrective, preventive, technical_legal or inspection_legal", "type": "string" }, "id": { "title": "Round template id", "type": "string" }, "interval_days": { "title": "Days between rounds", "type": "integer" }, "last_completed_on": { "format": "date", "title": "The property-local date its last round was completed", "type": "string" }, "name": { "title": "What the walk is called — unique among the house's active templates", "type": "string" }, "next_due_at": { "format": "date-time", "title": "The instant the house's day reaches next_due_on — its local midnight (UTC midnight when the house names no timezone); what the start sweep compares with the lane's clock", "type": "string" }, "next_due_on": { "format": "date", "title": "The date the next round is due", "type": "string" }, "open_round_id": { "title": "The round of this template in progress, when one is — the sweep starts none while it is set", "type": "string" }, "retired_at": { "format": "date-time", "title": "When the template was retired", "type": "string" }, "revision": { "title": "Which revision of the walk this is — 1 when defined, one more each time a re-definition moves its checkpoints (words and schedule do not); absent on a template defined before revisions, which reads as 1. start_inspection_round's template_revision is checked against it", "type": "integer" }, "status": { "enum": [ "active", "retired" ], "title": "Active (falls due) or retired", "type": "string" } }, "required": [ "id", "name", "family", "cadence", "interval_days", "next_due_on", "checkpoints", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.round_template:read" ] } ], "summary": "Read Round template", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.round_template/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA house's planned walk — hubOS's revision structure: a name, a `family` (corrective, preventive, technical_legal, inspection_legal), the maintenance plan's cadence (`fixed` to the calendar or `floating` from the last completion, every `interval_days`) and its next due date, and the `checkpoints` in order — each a room or a piece of equipment of this house (`ref_id`), or a general place named by its `label`, with the items checked there (`check`, `reading` with its unit and optional `min` / `max`, `text`, `photo`, and `section` headings). One active template per house and name: defining the name again revises it in place. The automation lane is its clock: a sweep over active templates whose due instant has come (`next_due_at`, the house's midnight starting `next_due_on`) and that have no round open starts one (`start_inspection_round`); completing the round moves `next_due_on` on. `open_round_id` names the round in progress; `revision` counts the walks it has defined (a re-definition that moves the checkpoints is the next), and a start may name the one it saw.", "operationId": "get_hospitality_round_template_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.round_template" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.round_template:read" ] } ], "summary": "Read Round template as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.round_template/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA house's planned walk — hubOS's revision structure: a name, a `family` (corrective, preventive, technical_legal, inspection_legal), the maintenance plan's cadence (`fixed` to the calendar or `floating` from the last completion, every `interval_days`) and its next due date, and the `checkpoints` in order — each a room or a piece of equipment of this house (`ref_id`), or a general place named by its `label`, with the items checked there (`check`, `reading` with its unit and optional `min` / `max`, `text`, `photo`, and `section` headings). One active template per house and name: defining the name again revises it in place. The automation lane is its clock: a sweep over active templates whose due instant has come (`next_due_at`, the house's midnight starting `next_due_on`) and that have no round open starts one (`start_inspection_round`); completing the round moves `next_due_on` on. `open_round_id` names the round in progress; `revision` counts the walks it has defined (a re-definition that moves the checkpoints is the next), and a start may name the one it saw.", "operationId": "list_links_hospitality_round_template", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.round_template:read" ] } ], "summary": "List links of Round template", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.inspection_round_from_template", "hospitality.link.round_template_at_property" ] } } ] }, "/v1/object-types/hospitality.round_template/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA house's planned walk — hubOS's revision structure: a name, a `family` (corrective, preventive, technical_legal, inspection_legal), the maintenance plan's cadence (`fixed` to the calendar or `floating` from the last completion, every `interval_days`) and its next due date, and the `checkpoints` in order — each a room or a piece of equipment of this house (`ref_id`), or a general place named by its `label`, with the items checked there (`check`, `reading` with its unit and optional `min` / `max`, `text`, `photo`, and `section` headings). One active template per house and name: defining the name again revises it in place. The automation lane is its clock: a sweep over active templates whose due instant has come (`next_due_at`, the house's midnight starting `next_due_on`) and that have no round open starts one (`start_inspection_round`); completing the round moves `next_due_on` on. `open_round_id` names the round in progress; `revision` counts the walks it has defined (a re-definition that moves the checkpoints is the next), and a start may name the one it saw.", "operationId": "traverse_hospitality_round_template", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.inspection_round_from_template", "hospitality.link.round_template_at_property" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.round_template:read" ] } ], "summary": "Traverse from Round template", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.round_template/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA house's planned walk — hubOS's revision structure: a name, a `family` (corrective, preventive, technical_legal, inspection_legal), the maintenance plan's cadence (`fixed` to the calendar or `floating` from the last completion, every `interval_days`) and its next due date, and the `checkpoints` in order — each a room or a piece of equipment of this house (`ref_id`), or a general place named by its `label`, with the items checked there (`check`, `reading` with its unit and optional `min` / `max`, `text`, `photo`, and `section` headings). One active template per house and name: defining the name again revises it in place. The automation lane is its clock: a sweep over active templates whose due instant has come (`next_due_at`, the house's midnight starting `next_due_on`) and that have no round open starts one (`start_inspection_round`); completing the round moves `next_due_on` on. `open_round_id` names the round in progress; `revision` counts the walks it has defined (a re-definition that moves the checkpoints is the next), and a start may name the one it saw.", "operationId": "search_hospitality_round_template", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "family" }, "type": { "const": "eq" }, "value": { "enum": [ "corrective", "preventive", "technical_legal", "inspection_legal" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cadence" }, "type": { "const": "eq" }, "value": { "enum": [ "fixed", "floating" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "interval_days" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "interval_days" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "interval_days" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_due_on" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_due_on" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_due_on" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_due_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_due_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_due_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checkpoints" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "items": { "items": { "properties": { "code": { "type": "string" }, "kind": { "enum": [ "check", "reading", "text", "photo", "section" ], "type": "string" }, "label": { "type": "string" }, "max": { "format": "decimal", "type": "string" }, "min": { "format": "decimal", "type": "string" }, "unit": { "type": "string" } }, "required": [ "code", "label", "kind" ], "type": "object" }, "type": "array" }, "kind": { "enum": [ "room", "asset", "general" ], "type": "string" }, "label": { "type": "string" }, "position": { "type": "integer" }, "ref_id": { "type": "string" } }, "required": [ "position", "kind", "items" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "retired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "open_round_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "open_round_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "open_round_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "open_round_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_completed_on" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_completed_on" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_completed_on" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revision" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revision" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revision" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "name", "description", "family", "cadence", "interval_days", "next_due_on", "next_due_at", "status", "open_round_id", "last_completed_on", "retired_at", "revision" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.round_template" }, "properties": { "additionalProperties": false, "properties": { "cadence": { "enum": [ "fixed", "floating" ], "title": "Fixed to the calendar, or floating from the last completion", "type": "string" }, "checkpoints": { "description": "The checkpoints, in walking order, each with its items", "items": { "properties": { "items": { "items": { "properties": { "code": { "type": "string" }, "kind": { "enum": [ "check", "reading", "text", "photo", "section" ], "type": "string" }, "label": { "type": "string" }, "max": { "format": "decimal", "type": "string" }, "min": { "format": "decimal", "type": "string" }, "unit": { "type": "string" } }, "required": [ "code", "label", "kind" ], "type": "object" }, "type": "array" }, "kind": { "enum": [ "room", "asset", "general" ], "type": "string" }, "label": { "type": "string" }, "position": { "type": "integer" }, "ref_id": { "type": "string" } }, "required": [ "position", "kind", "items" ], "type": "object" }, "title": "Round template checkpoints", "type": "array" }, "description": { "title": "What the walk is for, in words", "type": "string" }, "family": { "enum": [ "corrective", "preventive", "technical_legal", "inspection_legal" ], "title": "corrective, preventive, technical_legal or inspection_legal", "type": "string" }, "id": { "title": "Round template id", "type": "string" }, "interval_days": { "title": "Days between rounds", "type": "integer" }, "last_completed_on": { "format": "date", "title": "The property-local date its last round was completed", "type": "string" }, "name": { "title": "What the walk is called — unique among the house's active templates", "type": "string" }, "next_due_at": { "format": "date-time", "title": "The instant the house's day reaches next_due_on — its local midnight (UTC midnight when the house names no timezone); what the start sweep compares with the lane's clock", "type": "string" }, "next_due_on": { "format": "date", "title": "The date the next round is due", "type": "string" }, "open_round_id": { "title": "The round of this template in progress, when one is — the sweep starts none while it is set", "type": "string" }, "retired_at": { "format": "date-time", "title": "When the template was retired", "type": "string" }, "revision": { "title": "Which revision of the walk this is — 1 when defined, one more each time a re-definition moves its checkpoints (words and schedule do not); absent on a template defined before revisions, which reads as 1. start_inspection_round's template_revision is checked against it", "type": "integer" }, "status": { "enum": [ "active", "retired" ], "title": "Active (falls due) or retired", "type": "string" } }, "required": [ "id", "name", "family", "cadence", "interval_days", "next_due_on", "checkpoints", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.round_template:read" ] } ], "summary": "Search Round template", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.sell_limit_recommendation/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA typed overbooking recommendation issued by an agent against one room type over a date range: the oversell headroom the type may sell past its sellable rooms on every night of the range (`oversell_limit`), or the explicit `reset` to the operator's declared limit — with the reading behind it frozen at issue: the rooms on the books, the share of them believed to arrive, the walk cost and the marginal rate the limit balances, and the walks expected at it. Applying it moves each ledger row's `oversell_limit` through the overlay `set_availability` writes, bounded by the row's `oversell_ceiling` (the declared limit where none is set) and by what is already sold. The decision_* fields mutate exactly once on the transition out of `suggested`.", "operationId": "get_hospitality_sell_limit_recommendation", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.sell_limit_recommendation" }, "properties": { "additionalProperties": false, "properties": { "applied_oversell_limit": { "description": "The oversell headroom the apply wrote on the first night (for a reset, the declared limit it restored there)", "title": "Applied oversell limit", "type": "integer" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Operator-facing confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Calibrated probability (0..=1) — set when the model emits one", "type": "string" }, "decided_at": { "format": "date-time", "title": "When the recommendation transitioned out of suggested", "type": "string" }, "decision_status": { "enum": [ "suggested", "applied", "modified_and_applied", "rejected", "expired", "superseded" ], "title": "Lifecycle state", "type": "string" }, "end_date": { "description": "Last night the limit would cover (inclusive)", "format": "date", "title": "Last night", "type": "string" }, "expected_walks": { "description": "Guests the recommender expects to walk on the first night at the recommended limit", "format": "decimal", "title": "Expected walks", "type": "string" }, "expires_at": { "format": "date-time", "title": "After this, decision_status moves to expired", "type": "string" }, "expires_on": { "format": "date", "title": "The house business day this lapses after. When set, the house's open business date decides expiry (not the wall clock) and expires_at is the nominal end of that day in the house's timezone", "type": "string" }, "factors_considered": { "items": { "enum": [ "pickup_pace", "booking_curve", "competitive_set", "event_calendar", "historical_pattern", "segment_mix", "channel_mix", "length_of_stay_distribution", "cancellation_rate", "no_show_rate", "package_attachment", "group_displacement", "weather", "other" ], "type": "string" }, "title": "Signals the recommendation conditioned on", "type": "array" }, "forecast_snapshot": { "description": "Forecast snapshot frozen at issue time (per §B.2)", "properties": { "ari_score": { "format": "decimal", "type": "string" }, "as_of": { "format": "date-time", "type": "string" }, "competitive_set_adr": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "competitive_set_occupancy_pct": { "format": "decimal", "type": "string" }, "event_calendar_signal": { "type": "string" }, "forecast_kind": { "enum": [ "internal_pms", "external_rms", "external_str_compset", "hybrid", "other" ], "type": "string" }, "mpi_score": { "format": "decimal", "type": "string" }, "on_books_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "on_books_rooms": { "type": "integer" }, "pickup_last_24h": { "type": "integer" }, "pickup_last_7d": { "type": "integer" }, "rgi_score": { "format": "decimal", "type": "string" }, "transient_adr_forecast": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "transient_rooms_forecast": { "type": "integer" } }, "required": [ "forecast_kind", "as_of" ], "title": "Sell-limit recommendation forecast snapshot", "type": "object" }, "id": { "title": "Recommendation id", "type": "string" }, "issued_at": { "format": "date-time", "title": "When the agent emitted the recommendation", "type": "string" }, "marginal_rate": { "description": "The nightly rate one more sale on the first night would earn", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Sell-limit recommendation marginal rate", "type": "object" }, "oversell_limit": { "description": "Oversell headroom recommended over the sellable rooms on every night of the range (rooms; absent on a reset)", "title": "Oversell limit", "type": "integer" }, "rationale_text": { "title": "Human-readable explanation surfaced to operators", "type": "string" }, "rejection_reason": { "title": "Free-text reason set on reject", "type": "string" }, "reset": { "description": "Recommend returning the limit to the operator's declared one", "title": "Reset", "type": "boolean" }, "rooms_on_books": { "description": "Rooms of the type on the books for the first night, at issue time", "title": "Rooms on books", "type": "integer" }, "show_rate": { "description": "Share of the rooms on the books the recommender believes will arrive on the first night (0..=1)", "format": "decimal", "title": "Show rate", "type": "string" }, "start_date": { "description": "First night the limit would cover", "format": "date", "title": "First night", "type": "string" }, "walk_cost": { "description": "What the recommender believes walking one arriving guest costs the house, past the night's own revenue", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Sell-limit recommendation walk cost", "type": "object" } }, "required": [ "id", "start_date", "end_date", "confidence", "factors_considered", "issued_at", "expires_at", "decision_status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.sell_limit_recommendation:read" ] } ], "summary": "Read Sell-limit recommendation", "tags": [ "revenue_management" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.sell_limit_recommendation/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA typed overbooking recommendation issued by an agent against one room type over a date range: the oversell headroom the type may sell past its sellable rooms on every night of the range (`oversell_limit`), or the explicit `reset` to the operator's declared limit — with the reading behind it frozen at issue: the rooms on the books, the share of them believed to arrive, the walk cost and the marginal rate the limit balances, and the walks expected at it. Applying it moves each ledger row's `oversell_limit` through the overlay `set_availability` writes, bounded by the row's `oversell_ceiling` (the declared limit where none is set) and by what is already sold. The decision_* fields mutate exactly once on the transition out of `suggested`.", "operationId": "get_hospitality_sell_limit_recommendation_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.sell_limit_recommendation" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.sell_limit_recommendation:read" ] } ], "summary": "Read Sell-limit recommendation as of a watermark", "tags": [ "revenue_management" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.sell_limit_recommendation/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA typed overbooking recommendation issued by an agent against one room type over a date range: the oversell headroom the type may sell past its sellable rooms on every night of the range (`oversell_limit`), or the explicit `reset` to the operator's declared limit — with the reading behind it frozen at issue: the rooms on the books, the share of them believed to arrive, the walk cost and the marginal rate the limit balances, and the walks expected at it. Applying it moves each ledger row's `oversell_limit` through the overlay `set_availability` writes, bounded by the row's `oversell_ceiling` (the declared limit where none is set) and by what is already sold. The decision_* fields mutate exactly once on the transition out of `suggested`.", "operationId": "list_links_hospitality_sell_limit_recommendation", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.sell_limit_recommendation:read" ] } ], "summary": "List links of Sell-limit recommendation", "tags": [ "revenue_management" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.sell_limit_recommendation_applied_to_availability_day", "hospitality.link.sell_limit_recommendation_at_property", "hospitality.link.sell_limit_recommendation_for_room_type", "hospitality.link.sell_limit_recommendation_part_of_run", "hospitality.link.sell_limit_recommendation_superseded_by" ] } } ] }, "/v1/object-types/hospitality.sell_limit_recommendation/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA typed overbooking recommendation issued by an agent against one room type over a date range: the oversell headroom the type may sell past its sellable rooms on every night of the range (`oversell_limit`), or the explicit `reset` to the operator's declared limit — with the reading behind it frozen at issue: the rooms on the books, the share of them believed to arrive, the walk cost and the marginal rate the limit balances, and the walks expected at it. Applying it moves each ledger row's `oversell_limit` through the overlay `set_availability` writes, bounded by the row's `oversell_ceiling` (the declared limit where none is set) and by what is already sold. The decision_* fields mutate exactly once on the transition out of `suggested`.", "operationId": "traverse_hospitality_sell_limit_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.sell_limit_recommendation_applied_to_availability_day", "hospitality.link.sell_limit_recommendation_at_property", "hospitality.link.sell_limit_recommendation_for_room_type", "hospitality.link.sell_limit_recommendation_part_of_run", "hospitality.link.sell_limit_recommendation_superseded_by" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.sell_limit_recommendation:read" ] } ], "summary": "Traverse from Sell-limit recommendation", "tags": [ "revenue_management" ] } }, "/v1/object-types/hospitality.sell_limit_recommendation/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA typed overbooking recommendation issued by an agent against one room type over a date range: the oversell headroom the type may sell past its sellable rooms on every night of the range (`oversell_limit`), or the explicit `reset` to the operator's declared limit — with the reading behind it frozen at issue: the rooms on the books, the share of them believed to arrive, the walk cost and the marginal rate the limit balances, and the walks expected at it. Applying it moves each ledger row's `oversell_limit` through the overlay `set_availability` writes, bounded by the row's `oversell_ceiling` (the declared limit where none is set) and by what is already sold. The decision_* fields mutate exactly once on the transition out of `suggested`.", "operationId": "search_hospitality_sell_limit_recommendation", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "start_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "start_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "start_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "end_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "end_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "end_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "oversell_limit" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "oversell_limit" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "oversell_limit" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reset" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rooms_on_books" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rooms_on_books" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rooms_on_books" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "show_rate" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "show_rate" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "show_rate" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "walk_cost" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "marginal_rate" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expected_walks" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expected_walks" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expected_walks" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confidence" }, "type": { "const": "eq" }, "value": { "enum": [ "low", "medium", "high" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confidence_score" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confidence_score" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confidence_score" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "factors_considered" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "pickup_pace", "booking_curve", "competitive_set", "event_calendar", "historical_pattern", "segment_mix", "channel_mix", "length_of_stay_distribution", "cancellation_rate", "no_show_rate", "package_attachment", "group_displacement", "weather", "other" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rationale_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rationale_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "forecast_snapshot" }, "type": { "const": "eq" }, "value": { "properties": { "ari_score": { "format": "decimal", "type": "string" }, "as_of": { "format": "date-time", "type": "string" }, "competitive_set_adr": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "competitive_set_occupancy_pct": { "format": "decimal", "type": "string" }, "event_calendar_signal": { "type": "string" }, "forecast_kind": { "enum": [ "internal_pms", "external_rms", "external_str_compset", "hybrid", "other" ], "type": "string" }, "mpi_score": { "format": "decimal", "type": "string" }, "on_books_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "on_books_rooms": { "type": "integer" }, "pickup_last_24h": { "type": "integer" }, "pickup_last_7d": { "type": "integer" }, "rgi_score": { "format": "decimal", "type": "string" }, "transient_adr_forecast": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "transient_rooms_forecast": { "type": "integer" } }, "required": [ "forecast_kind", "as_of" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_on" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_on" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_on" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decision_status" }, "type": { "const": "eq" }, "value": { "enum": [ "suggested", "applied", "modified_and_applied", "rejected", "expired", "superseded" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_oversell_limit" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_oversell_limit" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_oversell_limit" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejection_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejection_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "start_date", "end_date", "oversell_limit", "rooms_on_books", "show_rate", "expected_walks", "confidence", "confidence_score", "rationale_text", "issued_at", "expires_at", "expires_on", "decision_status", "decided_at", "applied_oversell_limit", "rejection_reason" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.sell_limit_recommendation" }, "properties": { "additionalProperties": false, "properties": { "applied_oversell_limit": { "description": "The oversell headroom the apply wrote on the first night (for a reset, the declared limit it restored there)", "title": "Applied oversell limit", "type": "integer" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Operator-facing confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Calibrated probability (0..=1) — set when the model emits one", "type": "string" }, "decided_at": { "format": "date-time", "title": "When the recommendation transitioned out of suggested", "type": "string" }, "decision_status": { "enum": [ "suggested", "applied", "modified_and_applied", "rejected", "expired", "superseded" ], "title": "Lifecycle state", "type": "string" }, "end_date": { "description": "Last night the limit would cover (inclusive)", "format": "date", "title": "Last night", "type": "string" }, "expected_walks": { "description": "Guests the recommender expects to walk on the first night at the recommended limit", "format": "decimal", "title": "Expected walks", "type": "string" }, "expires_at": { "format": "date-time", "title": "After this, decision_status moves to expired", "type": "string" }, "expires_on": { "format": "date", "title": "The house business day this lapses after. When set, the house's open business date decides expiry (not the wall clock) and expires_at is the nominal end of that day in the house's timezone", "type": "string" }, "factors_considered": { "items": { "enum": [ "pickup_pace", "booking_curve", "competitive_set", "event_calendar", "historical_pattern", "segment_mix", "channel_mix", "length_of_stay_distribution", "cancellation_rate", "no_show_rate", "package_attachment", "group_displacement", "weather", "other" ], "type": "string" }, "title": "Signals the recommendation conditioned on", "type": "array" }, "forecast_snapshot": { "description": "Forecast snapshot frozen at issue time (per §B.2)", "properties": { "ari_score": { "format": "decimal", "type": "string" }, "as_of": { "format": "date-time", "type": "string" }, "competitive_set_adr": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "competitive_set_occupancy_pct": { "format": "decimal", "type": "string" }, "event_calendar_signal": { "type": "string" }, "forecast_kind": { "enum": [ "internal_pms", "external_rms", "external_str_compset", "hybrid", "other" ], "type": "string" }, "mpi_score": { "format": "decimal", "type": "string" }, "on_books_revenue": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "on_books_rooms": { "type": "integer" }, "pickup_last_24h": { "type": "integer" }, "pickup_last_7d": { "type": "integer" }, "rgi_score": { "format": "decimal", "type": "string" }, "transient_adr_forecast": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "transient_rooms_forecast": { "type": "integer" } }, "required": [ "forecast_kind", "as_of" ], "title": "Sell-limit recommendation forecast snapshot", "type": "object" }, "id": { "title": "Recommendation id", "type": "string" }, "issued_at": { "format": "date-time", "title": "When the agent emitted the recommendation", "type": "string" }, "marginal_rate": { "description": "The nightly rate one more sale on the first night would earn", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Sell-limit recommendation marginal rate", "type": "object" }, "oversell_limit": { "description": "Oversell headroom recommended over the sellable rooms on every night of the range (rooms; absent on a reset)", "title": "Oversell limit", "type": "integer" }, "rationale_text": { "title": "Human-readable explanation surfaced to operators", "type": "string" }, "rejection_reason": { "title": "Free-text reason set on reject", "type": "string" }, "reset": { "description": "Recommend returning the limit to the operator's declared one", "title": "Reset", "type": "boolean" }, "rooms_on_books": { "description": "Rooms of the type on the books for the first night, at issue time", "title": "Rooms on books", "type": "integer" }, "show_rate": { "description": "Share of the rooms on the books the recommender believes will arrive on the first night (0..=1)", "format": "decimal", "title": "Show rate", "type": "string" }, "start_date": { "description": "First night the limit would cover", "format": "date", "title": "First night", "type": "string" }, "walk_cost": { "description": "What the recommender believes walking one arriving guest costs the house, past the night's own revenue", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Sell-limit recommendation walk cost", "type": "object" } }, "required": [ "id", "start_date", "end_date", "confidence", "factors_considered", "issued_at", "expires_at", "decision_status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.sell_limit_recommendation:read" ] } ], "summary": "Search Sell-limit recommendation", "tags": [ "revenue_management" ] } }, "/v1/object-types/hospitality.service_area/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA named region of an outlet's floor — main dining, patio, bar, private room. The floor-plan render groups tables by area. Configuration: CRUD-authored, linked to its outlet via service_area_of_outlet.", "operationId": "get_hospitality_service_area", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_area" }, "properties": { "additionalProperties": false, "properties": { "active": { "title": "Active", "type": "boolean" }, "id": { "title": "Area id", "type": "string" }, "kind": { "enum": [ "dining_room", "bar", "counter", "patio", "terrace", "private_room", "lounge", "to_go", "other" ], "title": "Area kind", "type": "string" }, "name": { "title": "Area name", "type": "string" } }, "required": [ "id", "name", "kind", "active" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_area:read" ] } ], "summary": "Read Service area", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.service_area/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA named region of an outlet's floor — main dining, patio, bar, private room. The floor-plan render groups tables by area. Configuration: CRUD-authored, linked to its outlet via service_area_of_outlet.", "operationId": "get_hospitality_service_area_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.service_area" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_area:read" ] } ], "summary": "Read Service area as of a watermark", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.service_area/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA named region of an outlet's floor — main dining, patio, bar, private room. The floor-plan render groups tables by area. Configuration: CRUD-authored, linked to its outlet via service_area_of_outlet.", "operationId": "list_links_hospitality_service_area", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_area:read" ] } ], "summary": "List links of Service area", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.service_area_of_outlet", "hospitality.link.service_table_in_area" ] } } ] }, "/v1/object-types/hospitality.service_area/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA named region of an outlet's floor — main dining, patio, bar, private room. The floor-plan render groups tables by area. Configuration: CRUD-authored, linked to its outlet via service_area_of_outlet.", "operationId": "traverse_hospitality_service_area", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.service_area_of_outlet", "hospitality.link.service_table_in_area" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_area:read" ] } ], "summary": "Traverse from Service area", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.service_area/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA named region of an outlet's floor — main dining, patio, bar, private room. The floor-plan render groups tables by area. Configuration: CRUD-authored, linked to its outlet via service_area_of_outlet.", "operationId": "search_hospitality_service_area", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "dining_room", "bar", "counter", "patio", "terrace", "private_room", "lounge", "to_go", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "active" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "name", "kind" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_area" }, "properties": { "additionalProperties": false, "properties": { "active": { "title": "Active", "type": "boolean" }, "id": { "title": "Area id", "type": "string" }, "kind": { "enum": [ "dining_room", "bar", "counter", "patio", "terrace", "private_room", "lounge", "to_go", "other" ], "title": "Area kind", "type": "string" }, "name": { "title": "Area name", "type": "string" } }, "required": [ "id", "name", "kind", "active" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_area:read" ] } ], "summary": "Search Service area", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.service_item/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA saleable item or service offered by a venue: a menu item, a spa treatment, an activity booking, a retail product. Charges link to service items so revenue can be analysed by venue and category.", "operationId": "get_hospitality_service_item", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_item" }, "properties": { "additionalProperties": false, "properties": { "category": { "enum": [ "food", "beverage", "spa", "activity", "retail", "room_service", "package", "transport", "tour", "other" ], "title": "Category", "type": "string" }, "code": { "title": "Item code", "type": "string" }, "description": { "title": "Description", "type": "string" }, "name": { "title": "Item name", "type": "string" }, "price": { "description": "Price", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Service item price", "type": "object" }, "tax_inclusive": { "title": "Tax inclusive", "type": "boolean" } }, "required": [ "code", "name", "category", "price", "tax_inclusive" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_item:read" ] } ], "summary": "Read Service item", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.service_item/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA saleable item or service offered by a venue: a menu item, a spa treatment, an activity booking, a retail product. Charges link to service items so revenue can be analysed by venue and category.", "operationId": "get_hospitality_service_item_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.service_item" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_item:read" ] } ], "summary": "Read Service item as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.service_item/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA saleable item or service offered by a venue: a menu item, a spa treatment, an activity booking, a retail product. Charges link to service items so revenue can be analysed by venue and category.", "operationId": "list_links_hospitality_service_item", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_item:read" ] } ], "summary": "List links of Service item", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.banquet_order_line_for_service_item", "hospitality.link.charge_for_service_item", "hospitality.link.package_component_targets_service_item", "hospitality.link.recipe_for_service_item", "hospitality.link.service_item_is_retail_product", "hospitality.link.venue_has_service_item" ] } } ] }, "/v1/object-types/hospitality.service_item/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA saleable item or service offered by a venue: a menu item, a spa treatment, an activity booking, a retail product. Charges link to service items so revenue can be analysed by venue and category.", "operationId": "traverse_hospitality_service_item", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.banquet_order_line_for_service_item", "hospitality.link.charge_for_service_item", "hospitality.link.package_component_targets_service_item", "hospitality.link.recipe_for_service_item", "hospitality.link.service_item_is_retail_product", "hospitality.link.venue_has_service_item" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_item:read" ] } ], "summary": "Traverse from Service item", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.service_item/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA saleable item or service offered by a venue: a menu item, a spa treatment, an activity booking, a retail product. Charges link to service items so revenue can be analysed by venue and category.", "operationId": "search_hospitality_service_item", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "category" }, "type": { "const": "eq" }, "value": { "enum": [ "food", "beverage", "spa", "activity", "retail", "room_service", "package", "transport", "tour", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "price" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_inclusive" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "description", "category" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_item" }, "properties": { "additionalProperties": false, "properties": { "category": { "enum": [ "food", "beverage", "spa", "activity", "retail", "room_service", "package", "transport", "tour", "other" ], "title": "Category", "type": "string" }, "code": { "title": "Item code", "type": "string" }, "description": { "title": "Description", "type": "string" }, "name": { "title": "Item name", "type": "string" }, "price": { "description": "Price", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Service item price", "type": "object" }, "tax_inclusive": { "title": "Tax inclusive", "type": "boolean" } }, "required": [ "code", "name", "category", "price", "tax_inclusive" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_item:read" ] } ], "summary": "Search Service item", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.service_philosophy/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA property's typed service framework along nine ordinal axes plus its narrative statement and audit-target context. The framework decomposes patterns observed across Ritz-Carlton, Four Seasons, Aman, Soho House, Sydell, Maybourne, USHG, and the wider luxury-hospitality canon — types the difference between operators that look similar on a single axis but operate differently in practice (a Connaught bar and a NoMad bar both read 'warm-informal' on a one-dimensional axis but decompose to observably-different registers across surface, address form, and personality presentation). Recovery culture is deliberately not an axis — it's an outcome of the other axes plus the recovery toolkit, not an input the operator self-scores.", "operationId": "get_hospitality_service_philosophy", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_philosophy" }, "properties": { "additionalProperties": false, "properties": { "address_form_default": { "enum": [ "mr_ms", "first_name", "no_name" ], "title": "Address form default", "type": "string" }, "anticipatory_responsive": { "enum": [ "extremely_anticipatory", "anticipatory", "balanced", "responsive", "purely_responsive" ], "title": "Anticipatory ↔ responsive", "type": "string" }, "audit_target": { "enum": [ "forbes", "aaa_diamond", "lqa", "internal_only", "none" ], "title": "Audit target", "type": "string" }, "empowered_scripted": { "enum": [ "fully_empowered", "empowered_with_guidance", "balanced", "mostly_scripted", "fully_scripted" ], "title": "Empowered ↔ scripted", "type": "string" }, "ex_cx_priority": { "enum": [ "employees_first", "employees_above_guests", "employees_equal_guests", "guests_first", "investors_first" ], "title": "EX → CX priority (Meyer hierarchy stance)", "type": "string" }, "hospitality_service_emphasis": { "enum": [ "hospitality_first", "balanced_warm", "professional_warmth", "service_efficient", "transactional" ], "title": "Hospitality ↔ service emphasis", "type": "string" }, "id": { "title": "Philosophy id", "type": "string" }, "personality_presentation": { "enum": [ "muted", "forward", "as_product" ], "title": "Personality presentation", "type": "string" }, "philosophy_statement_text": { "title": "Philosophy narrative", "type": "string" }, "privacy_visibility_default": { "enum": [ "extremely_private_invisible_attention", "private", "balanced", "visible_attention", "extremely_visible" ], "title": "Privacy ↔ visibility default", "type": "string" }, "recognition_depth": { "enum": [ "minimal", "name_recognition", "preference_recognition", "relationship_recognition", "deep_recognition" ], "title": "Recognition depth", "type": "string" }, "recovery_culture_intent": { "title": "Recovery culture intent (self-declared)", "type": "string" }, "surface_register_default": { "enum": [ "formal_warm", "crafted_theatre", "quick_warm", "discreet_professional", "focused_coaching", "other" ], "title": "Surface register default", "type": "string" } }, "required": [ "id", "anticipatory_responsive", "empowered_scripted", "surface_register_default", "address_form_default", "personality_presentation", "recognition_depth", "privacy_visibility_default", "hospitality_service_emphasis", "ex_cx_priority", "audit_target", "philosophy_statement_text" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_philosophy:read" ] } ], "summary": "Read Service philosophy", "tags": [ "service_philosophy" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.service_philosophy/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA property's typed service framework along nine ordinal axes plus its narrative statement and audit-target context. The framework decomposes patterns observed across Ritz-Carlton, Four Seasons, Aman, Soho House, Sydell, Maybourne, USHG, and the wider luxury-hospitality canon — types the difference between operators that look similar on a single axis but operate differently in practice (a Connaught bar and a NoMad bar both read 'warm-informal' on a one-dimensional axis but decompose to observably-different registers across surface, address form, and personality presentation). Recovery culture is deliberately not an axis — it's an outcome of the other axes plus the recovery toolkit, not an input the operator self-scores.", "operationId": "get_hospitality_service_philosophy_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.service_philosophy" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_philosophy:read" ] } ], "summary": "Read Service philosophy as of a watermark", "tags": [ "service_philosophy" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.service_philosophy/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA property's typed service framework along nine ordinal axes plus its narrative statement and audit-target context. The framework decomposes patterns observed across Ritz-Carlton, Four Seasons, Aman, Soho House, Sydell, Maybourne, USHG, and the wider luxury-hospitality canon — types the difference between operators that look similar on a single axis but operate differently in practice (a Connaught bar and a NoMad bar both read 'warm-informal' on a one-dimensional axis but decompose to observably-different registers across surface, address form, and personality presentation). Recovery culture is deliberately not an axis — it's an outcome of the other axes plus the recovery toolkit, not an input the operator self-scores.", "operationId": "list_links_hospitality_service_philosophy", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_philosophy:read" ] } ], "summary": "List links of Service philosophy", "tags": [ "service_philosophy" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.pattern_references_service_philosophy", "hospitality.link.philosophy_has_recovery_toolkit", "hospitality.link.property_has_philosophy" ] } } ] }, "/v1/object-types/hospitality.service_philosophy/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA property's typed service framework along nine ordinal axes plus its narrative statement and audit-target context. The framework decomposes patterns observed across Ritz-Carlton, Four Seasons, Aman, Soho House, Sydell, Maybourne, USHG, and the wider luxury-hospitality canon — types the difference between operators that look similar on a single axis but operate differently in practice (a Connaught bar and a NoMad bar both read 'warm-informal' on a one-dimensional axis but decompose to observably-different registers across surface, address form, and personality presentation). Recovery culture is deliberately not an axis — it's an outcome of the other axes plus the recovery toolkit, not an input the operator self-scores.", "operationId": "traverse_hospitality_service_philosophy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.pattern_references_service_philosophy", "hospitality.link.philosophy_has_recovery_toolkit", "hospitality.link.property_has_philosophy" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_philosophy:read" ] } ], "summary": "Traverse from Service philosophy", "tags": [ "service_philosophy" ] } }, "/v1/object-types/hospitality.service_philosophy/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA property's typed service framework along nine ordinal axes plus its narrative statement and audit-target context. The framework decomposes patterns observed across Ritz-Carlton, Four Seasons, Aman, Soho House, Sydell, Maybourne, USHG, and the wider luxury-hospitality canon — types the difference between operators that look similar on a single axis but operate differently in practice (a Connaught bar and a NoMad bar both read 'warm-informal' on a one-dimensional axis but decompose to observably-different registers across surface, address form, and personality presentation). Recovery culture is deliberately not an axis — it's an outcome of the other axes plus the recovery toolkit, not an input the operator self-scores.", "operationId": "search_hospitality_service_philosophy", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "anticipatory_responsive" }, "type": { "const": "eq" }, "value": { "enum": [ "extremely_anticipatory", "anticipatory", "balanced", "responsive", "purely_responsive" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "empowered_scripted" }, "type": { "const": "eq" }, "value": { "enum": [ "fully_empowered", "empowered_with_guidance", "balanced", "mostly_scripted", "fully_scripted" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "surface_register_default" }, "type": { "const": "eq" }, "value": { "enum": [ "formal_warm", "crafted_theatre", "quick_warm", "discreet_professional", "focused_coaching", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "address_form_default" }, "type": { "const": "eq" }, "value": { "enum": [ "mr_ms", "first_name", "no_name" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "personality_presentation" }, "type": { "const": "eq" }, "value": { "enum": [ "muted", "forward", "as_product" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recognition_depth" }, "type": { "const": "eq" }, "value": { "enum": [ "minimal", "name_recognition", "preference_recognition", "relationship_recognition", "deep_recognition" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "privacy_visibility_default" }, "type": { "const": "eq" }, "value": { "enum": [ "extremely_private_invisible_attention", "private", "balanced", "visible_attention", "extremely_visible" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hospitality_service_emphasis" }, "type": { "const": "eq" }, "value": { "enum": [ "hospitality_first", "balanced_warm", "professional_warmth", "service_efficient", "transactional" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "ex_cx_priority" }, "type": { "const": "eq" }, "value": { "enum": [ "employees_first", "employees_above_guests", "employees_equal_guests", "guests_first", "investors_first" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "audit_target" }, "type": { "const": "eq" }, "value": { "enum": [ "forbes", "aaa_diamond", "lqa", "internal_only", "none" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "philosophy_statement_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "philosophy_statement_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recovery_culture_intent" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recovery_culture_intent" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "anticipatory_responsive", "empowered_scripted", "surface_register_default", "address_form_default", "personality_presentation", "recognition_depth", "privacy_visibility_default", "hospitality_service_emphasis", "ex_cx_priority", "audit_target", "philosophy_statement_text", "recovery_culture_intent" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_philosophy" }, "properties": { "additionalProperties": false, "properties": { "address_form_default": { "enum": [ "mr_ms", "first_name", "no_name" ], "title": "Address form default", "type": "string" }, "anticipatory_responsive": { "enum": [ "extremely_anticipatory", "anticipatory", "balanced", "responsive", "purely_responsive" ], "title": "Anticipatory ↔ responsive", "type": "string" }, "audit_target": { "enum": [ "forbes", "aaa_diamond", "lqa", "internal_only", "none" ], "title": "Audit target", "type": "string" }, "empowered_scripted": { "enum": [ "fully_empowered", "empowered_with_guidance", "balanced", "mostly_scripted", "fully_scripted" ], "title": "Empowered ↔ scripted", "type": "string" }, "ex_cx_priority": { "enum": [ "employees_first", "employees_above_guests", "employees_equal_guests", "guests_first", "investors_first" ], "title": "EX → CX priority (Meyer hierarchy stance)", "type": "string" }, "hospitality_service_emphasis": { "enum": [ "hospitality_first", "balanced_warm", "professional_warmth", "service_efficient", "transactional" ], "title": "Hospitality ↔ service emphasis", "type": "string" }, "id": { "title": "Philosophy id", "type": "string" }, "personality_presentation": { "enum": [ "muted", "forward", "as_product" ], "title": "Personality presentation", "type": "string" }, "philosophy_statement_text": { "title": "Philosophy narrative", "type": "string" }, "privacy_visibility_default": { "enum": [ "extremely_private_invisible_attention", "private", "balanced", "visible_attention", "extremely_visible" ], "title": "Privacy ↔ visibility default", "type": "string" }, "recognition_depth": { "enum": [ "minimal", "name_recognition", "preference_recognition", "relationship_recognition", "deep_recognition" ], "title": "Recognition depth", "type": "string" }, "recovery_culture_intent": { "title": "Recovery culture intent (self-declared)", "type": "string" }, "surface_register_default": { "enum": [ "formal_warm", "crafted_theatre", "quick_warm", "discreet_professional", "focused_coaching", "other" ], "title": "Surface register default", "type": "string" } }, "required": [ "id", "anticipatory_responsive", "empowered_scripted", "surface_register_default", "address_form_default", "personality_presentation", "recognition_depth", "privacy_visibility_default", "hospitality_service_emphasis", "ex_cx_priority", "audit_target", "philosophy_statement_text" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_philosophy:read" ] } ], "summary": "Search Service philosophy", "tags": [ "service_philosophy" ] } }, "/v1/object-types/hospitality.service_recovery_event/objects/{id}": { "get": { "description": "Read an existing instance.\n\nAn instance of service recovery — failure, recovery action, comp authority used, follow-up. The unit of pattern detection: the same failure logged repeatedly against one room reveals an HVAC issue; against one staff member, a training need; against one venue at one time-of-day, a capacity / staffing pattern. The USHG 5 As stages-completed set surfaces structural process gaps (the operator that consistently apologises but never reaches additional generosity is structurally different from the one that consistently acts but rarely apologises). The comp_authority_snapshot freezes the toolkit's role rules at recovery time so a later toolkit edit doesn't retroactively re-evaluate whether the recovery was within authority. Soft validators on over-limit comp warn but don't block — over-limit recoveries are the data the operator most needs and would otherwise hide.", "operationId": "get_hospitality_service_recovery_event", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_recovery_event" }, "properties": { "additionalProperties": false, "properties": { "comp_amount": { "description": "Comp amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Service recovery event comp amount", "type": "object" }, "comp_authority_policy_ref": { "format": "uuid", "title": "Comp authority policy bound at recovery time (structured ref)", "type": "string", "x-aerandil-references": "hospitality.comp_authority_policy" }, "comp_authority_snapshot": { "description": "Comp authority snapshot at recovery time", "properties": { "comp_categories_allowed_at_recovery": { "items": { "enum": [ "room_night", "food_beverage", "spa", "retail", "parking", "other" ], "type": "string" }, "type": "array" }, "flat_universal_per_incident_limit_at_recovery": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "per_incident_limit_at_recovery": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "per_shift_cumulative_at_recovery": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "policy_kind_at_recovery": { "type": "string" }, "role_code_at_recovery": { "type": "string" } }, "required": [ "policy_kind_at_recovery" ], "title": "Service recovery event comp authority snapshot", "type": "object" }, "comp_category": { "enum": [ "room_night", "food_beverage", "spa", "retail", "parking", "other" ], "title": "Comp category", "type": "string" }, "failure_category": { "enum": [ "staff_interaction", "room_condition", "fnb_quality", "fnb_service_pace", "billing", "allergy_dietary", "security_safety", "check_in_out", "maintenance", "recognition_failure", "anticipation_miss", "noise", "temperature", "other" ], "title": "Failure category", "type": "string" }, "failure_subject_text": { "title": "What went wrong", "type": "string" }, "follow_up_completed_at": { "format": "date-time", "title": "Follow-up completed at", "type": "string" }, "follow_up_due_at": { "format": "date-time", "title": "Follow-up due date", "type": "string" }, "follow_up_outcome": { "title": "Follow-up outcome", "type": "string" }, "happened_at": { "format": "date-time", "title": "When the failure happened", "type": "string" }, "id": { "title": "Recovery event id", "type": "string" }, "interactional_quality": { "enum": [ "failed", "adequate", "genuine", "excellent" ], "title": "How the recovery landed", "type": "string" }, "recovery_action_category": { "enum": [ "apology_only", "apology_plus_gesture", "apology_plus_comp", "apology_plus_upgrade", "complaint_handling_only", "gesture_declined_with_dignity", "escalated_unresolved" ], "title": "Recovery action category", "type": "string" }, "recovery_authoriser": { "title": "Authoriser principal", "type": "string" }, "recovery_process_stages_completed": { "items": { "enum": [ "aware", "acknowledge", "apologise", "act", "additional_generosity" ], "type": "string" }, "title": "USHG 5 As stages completed", "type": "array" }, "severity": { "enum": [ "minor", "moderate", "significant", "severe", "safety_health" ], "title": "Severity", "type": "string" }, "time_to_first_response_seconds": { "title": "Seconds until first response", "type": "integer" }, "time_to_resolution_seconds": { "title": "Seconds until resolved", "type": "integer" } }, "required": [ "id", "failure_category", "severity", "recovery_action_category", "recovery_process_stages_completed", "happened_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_recovery_event:read" ] } ], "summary": "Read Service recovery event", "tags": [ "service_philosophy" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.service_recovery_event/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nAn instance of service recovery — failure, recovery action, comp authority used, follow-up. The unit of pattern detection: the same failure logged repeatedly against one room reveals an HVAC issue; against one staff member, a training need; against one venue at one time-of-day, a capacity / staffing pattern. The USHG 5 As stages-completed set surfaces structural process gaps (the operator that consistently apologises but never reaches additional generosity is structurally different from the one that consistently acts but rarely apologises). The comp_authority_snapshot freezes the toolkit's role rules at recovery time so a later toolkit edit doesn't retroactively re-evaluate whether the recovery was within authority. Soft validators on over-limit comp warn but don't block — over-limit recoveries are the data the operator most needs and would otherwise hide.", "operationId": "get_hospitality_service_recovery_event_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.service_recovery_event" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_recovery_event:read" ] } ], "summary": "Read Service recovery event as of a watermark", "tags": [ "service_philosophy" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.service_recovery_event/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nAn instance of service recovery — failure, recovery action, comp authority used, follow-up. The unit of pattern detection: the same failure logged repeatedly against one room reveals an HVAC issue; against one staff member, a training need; against one venue at one time-of-day, a capacity / staffing pattern. The USHG 5 As stages-completed set surfaces structural process gaps (the operator that consistently apologises but never reaches additional generosity is structurally different from the one that consistently acts but rarely apologises). The comp_authority_snapshot freezes the toolkit's role rules at recovery time so a later toolkit edit doesn't retroactively re-evaluate whether the recovery was within authority. Soft validators on over-limit comp warn but don't block — over-limit recoveries are the data the operator most needs and would otherwise hide.", "operationId": "list_links_hospitality_service_recovery_event", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_recovery_event:read" ] } ], "summary": "List links of Service recovery event", "tags": [ "service_philosophy" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.pattern_clusters_recovery_event", "hospitality.link.recovery_event_for_person", "hospitality.link.recovery_event_in_venue", "hospitality.link.workflow_run_targets_service_recovery_event" ] } } ] }, "/v1/object-types/hospitality.service_recovery_event/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nAn instance of service recovery — failure, recovery action, comp authority used, follow-up. The unit of pattern detection: the same failure logged repeatedly against one room reveals an HVAC issue; against one staff member, a training need; against one venue at one time-of-day, a capacity / staffing pattern. The USHG 5 As stages-completed set surfaces structural process gaps (the operator that consistently apologises but never reaches additional generosity is structurally different from the one that consistently acts but rarely apologises). The comp_authority_snapshot freezes the toolkit's role rules at recovery time so a later toolkit edit doesn't retroactively re-evaluate whether the recovery was within authority. Soft validators on over-limit comp warn but don't block — over-limit recoveries are the data the operator most needs and would otherwise hide.", "operationId": "traverse_hospitality_service_recovery_event", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.pattern_clusters_recovery_event", "hospitality.link.recovery_event_for_person", "hospitality.link.recovery_event_in_venue", "hospitality.link.workflow_run_targets_service_recovery_event" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_recovery_event:read" ] } ], "summary": "Traverse from Service recovery event", "tags": [ "service_philosophy" ] } }, "/v1/object-types/hospitality.service_recovery_event/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nAn instance of service recovery — failure, recovery action, comp authority used, follow-up. The unit of pattern detection: the same failure logged repeatedly against one room reveals an HVAC issue; against one staff member, a training need; against one venue at one time-of-day, a capacity / staffing pattern. The USHG 5 As stages-completed set surfaces structural process gaps (the operator that consistently apologises but never reaches additional generosity is structurally different from the one that consistently acts but rarely apologises). The comp_authority_snapshot freezes the toolkit's role rules at recovery time so a later toolkit edit doesn't retroactively re-evaluate whether the recovery was within authority. Soft validators on over-limit comp warn but don't block — over-limit recoveries are the data the operator most needs and would otherwise hide.", "operationId": "search_hospitality_service_recovery_event", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "failure_category" }, "type": { "const": "eq" }, "value": { "enum": [ "staff_interaction", "room_condition", "fnb_quality", "fnb_service_pace", "billing", "allergy_dietary", "security_safety", "check_in_out", "maintenance", "recognition_failure", "anticipation_miss", "noise", "temperature", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "severity" }, "type": { "const": "eq" }, "value": { "enum": [ "minor", "moderate", "significant", "severe", "safety_health" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "failure_subject_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "failure_subject_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recovery_action_category" }, "type": { "const": "eq" }, "value": { "enum": [ "apology_only", "apology_plus_gesture", "apology_plus_comp", "apology_plus_upgrade", "complaint_handling_only", "gesture_declined_with_dignity", "escalated_unresolved" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recovery_process_stages_completed" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "aware", "acknowledge", "apologise", "act", "additional_generosity" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "comp_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "comp_category" }, "type": { "const": "eq" }, "value": { "enum": [ "room_night", "food_beverage", "spa", "retail", "parking", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "comp_authority_policy_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.comp_authority_policy" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "comp_authority_snapshot" }, "type": { "const": "eq" }, "value": { "properties": { "comp_categories_allowed_at_recovery": { "items": { "enum": [ "room_night", "food_beverage", "spa", "retail", "parking", "other" ], "type": "string" }, "type": "array" }, "flat_universal_per_incident_limit_at_recovery": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "per_incident_limit_at_recovery": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "per_shift_cumulative_at_recovery": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "policy_kind_at_recovery": { "type": "string" }, "role_code_at_recovery": { "type": "string" } }, "required": [ "policy_kind_at_recovery" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recovery_authoriser" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recovery_authoriser" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recovery_authoriser" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recovery_authoriser" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "time_to_first_response_seconds" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "time_to_first_response_seconds" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "time_to_first_response_seconds" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "time_to_resolution_seconds" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "time_to_resolution_seconds" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "time_to_resolution_seconds" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "interactional_quality" }, "type": { "const": "eq" }, "value": { "enum": [ "failed", "adequate", "genuine", "excellent" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "happened_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "happened_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "happened_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "follow_up_due_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "follow_up_due_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "follow_up_due_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "follow_up_completed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "follow_up_completed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "follow_up_completed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "follow_up_outcome" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "follow_up_outcome" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "failure_category", "severity", "failure_subject_text", "recovery_action_category", "comp_category", "recovery_authoriser", "time_to_first_response_seconds", "time_to_resolution_seconds", "interactional_quality", "happened_at", "follow_up_due_at", "follow_up_completed_at", "follow_up_outcome" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_recovery_event" }, "properties": { "additionalProperties": false, "properties": { "comp_amount": { "description": "Comp amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Service recovery event comp amount", "type": "object" }, "comp_authority_policy_ref": { "format": "uuid", "title": "Comp authority policy bound at recovery time (structured ref)", "type": "string", "x-aerandil-references": "hospitality.comp_authority_policy" }, "comp_authority_snapshot": { "description": "Comp authority snapshot at recovery time", "properties": { "comp_categories_allowed_at_recovery": { "items": { "enum": [ "room_night", "food_beverage", "spa", "retail", "parking", "other" ], "type": "string" }, "type": "array" }, "flat_universal_per_incident_limit_at_recovery": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "per_incident_limit_at_recovery": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "per_shift_cumulative_at_recovery": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "policy_kind_at_recovery": { "type": "string" }, "role_code_at_recovery": { "type": "string" } }, "required": [ "policy_kind_at_recovery" ], "title": "Service recovery event comp authority snapshot", "type": "object" }, "comp_category": { "enum": [ "room_night", "food_beverage", "spa", "retail", "parking", "other" ], "title": "Comp category", "type": "string" }, "failure_category": { "enum": [ "staff_interaction", "room_condition", "fnb_quality", "fnb_service_pace", "billing", "allergy_dietary", "security_safety", "check_in_out", "maintenance", "recognition_failure", "anticipation_miss", "noise", "temperature", "other" ], "title": "Failure category", "type": "string" }, "failure_subject_text": { "title": "What went wrong", "type": "string" }, "follow_up_completed_at": { "format": "date-time", "title": "Follow-up completed at", "type": "string" }, "follow_up_due_at": { "format": "date-time", "title": "Follow-up due date", "type": "string" }, "follow_up_outcome": { "title": "Follow-up outcome", "type": "string" }, "happened_at": { "format": "date-time", "title": "When the failure happened", "type": "string" }, "id": { "title": "Recovery event id", "type": "string" }, "interactional_quality": { "enum": [ "failed", "adequate", "genuine", "excellent" ], "title": "How the recovery landed", "type": "string" }, "recovery_action_category": { "enum": [ "apology_only", "apology_plus_gesture", "apology_plus_comp", "apology_plus_upgrade", "complaint_handling_only", "gesture_declined_with_dignity", "escalated_unresolved" ], "title": "Recovery action category", "type": "string" }, "recovery_authoriser": { "title": "Authoriser principal", "type": "string" }, "recovery_process_stages_completed": { "items": { "enum": [ "aware", "acknowledge", "apologise", "act", "additional_generosity" ], "type": "string" }, "title": "USHG 5 As stages completed", "type": "array" }, "severity": { "enum": [ "minor", "moderate", "significant", "severe", "safety_health" ], "title": "Severity", "type": "string" }, "time_to_first_response_seconds": { "title": "Seconds until first response", "type": "integer" }, "time_to_resolution_seconds": { "title": "Seconds until resolved", "type": "integer" } }, "required": [ "id", "failure_category", "severity", "recovery_action_category", "recovery_process_stages_completed", "happened_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_recovery_event:read" ] } ], "summary": "Search Service recovery event", "tags": [ "service_philosophy" ] } }, "/v1/object-types/hospitality.service_recovery_pattern/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA property-scoped recurring-service-failure pattern detected by an agent or model. The subject, evidence snapshot, hypotheses, severity, confidence, and recommended remediation are frozen at issue time. Decision, applied, escalation, rejection, supersedence, and recurrence fields mutate through explicit lifecycle actions.", "operationId": "get_hospitality_service_recovery_pattern", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_recovery_pattern" }, "properties": { "additionalProperties": false, "properties": { "applied_action_correlation_id": { "title": "Correlation id of host-orchestrated chained remediation", "type": "string" }, "applied_remediation_kind": { "enum": [ "work_order_created", "recovery_toolkit_updated", "service_register_updated", "staff_training_referred", "engineering_referred", "supply_chain_referred", "philosophy_revisited", "lineup_cadence_corrected", "manual_intervention", "no_action_applied" ], "title": "Remediation class actually applied", "type": "string" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Operator-facing confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Optional calibrated confidence score [0, 1]", "type": "string" }, "decided_at": { "format": "date-time", "title": "When the pattern left suggested state", "type": "string" }, "decided_by": { "title": "stable_id of the deciding principal", "type": "string" }, "decision_status": { "enum": [ "suggested", "applied", "rejected", "escalated", "expired", "superseded" ], "title": "Lifecycle state", "type": "string" }, "detection_window_end": { "format": "date-time", "title": "End of the frozen detection window", "type": "string" }, "detection_window_start": { "format": "date-time", "title": "Start of the frozen detection window", "type": "string" }, "escalation_reason": { "enum": [ "high_severity", "capital_expenditure_required", "safety_health_concern", "training_program_redesign_needed", "regulatory_concern", "cross_property_pattern", "repeat_unresolved", "low_confidence", "manual_review_required", "operator_override" ], "title": "Reason recorded on escalation", "type": "string" }, "escalation_target_staff_ref": { "format": "uuid", "title": "Optional named staff member assigned on escalation", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "event_count": { "title": "Number of clustered events", "type": "integer" }, "expires_at": { "format": "date-time", "title": "Expiry time", "type": "string" }, "factors_considered": { "items": { "enum": [ "recovery_event_density", "recovery_event_severity_distribution", "recovery_event_temporal_clustering", "recovery_event_venue_clustering", "recovery_event_room_clustering", "comp_amount_distribution", "recovery_process_stages_completion_rate", "interactional_quality_distribution", "time_to_resolution_distribution", "pre_shift_lineup_cadence", "message_triage_complaint_density", "work_order_recurrence", "housekeeping_task_defect_rate", "review_sentiment_trend", "philosophy_axis_contradiction", "recovery_paradox_signal", "staff_member_turnover", "other" ], "type": "string" }, "title": "Signals considered by the detector", "type": "array" }, "failure_categories_observed": { "items": { "enum": [ "staff_interaction", "room_condition", "fnb_quality", "fnb_service_pace", "billing", "allergy_dietary", "security_safety", "check_in_out", "maintenance", "recognition_failure", "anticipation_miss", "noise", "temperature", "other" ], "type": "string" }, "title": "Observed service-failure categories", "type": "array" }, "failure_subject_themes": { "items": { "type": "string" }, "title": "Free-text theme labels for the clustered subject", "type": "array" }, "id": { "title": "Pattern id", "type": "string" }, "issued_at": { "format": "date-time", "title": "Issue time", "type": "string" }, "pattern_context_snapshot": { "title": "Frozen context snapshot captured at issue time" }, "pattern_kind": { "enum": [ "recurring_failure_category", "venue_hotspot", "room_or_floor_hotspot", "time_window_hotspot", "staff_role_hotspot", "cross_signal_correlation", "comp_authority_breach_spike", "lineup_cadence_drift", "recognition_failure_against_philosophy", "recovery_paradox_breach", "follow_up_completion_drop", "other" ], "title": "Detected pattern class", "type": "string" }, "pattern_payload_hash": { "title": "Optional SHA-256 of canonical detector payload", "type": "string" }, "policy_outcomes": { "items": { "enum": [ "gdpr_art22_explanation_required", "eu_ai_act_high_risk_processing", "ccpa_admt_notice_required", "health_safety_referral", "gdpr_art9_special_category_present", "privacy_redaction_applied", "ccpa_admt_significant_decision", "capex_threshold_breached", "none" ], "type": "string" }, "title": "Compliance and operational policy flags observed during detection", "type": "array" }, "property_ref": { "format": "uuid", "title": "Property anchor for the pattern", "type": "string", "x-aerandil-references": "hospitality.property" }, "rationale_text": { "title": "Human-readable explanation", "type": "string" }, "recommended_remediation_action_ref": { "title": "API name of the host-orchestrated chained action, when applicable", "type": "string" }, "recommended_remediation_kind": { "enum": [ "chain_typed_action", "schedule_capital_expenditure_review", "escalate_to_staff", "philosophy_revisit", "continue_monitoring", "cross_property_review", "update_service_register", "no_action_recommended", "update_recovery_toolkit", "data_quality_followup", "schedule_staff_training", "other" ], "title": "Recommended remediation class", "type": "string" }, "recommended_remediation_params": { "title": "Proposed chained-action parameters or workflow payload" }, "recurrence_outcome": { "enum": [ "decayed_to_zero", "decayed_significantly", "decayed_partially", "unchanged", "worsened", "not_measurable" ], "title": "Observed recurrence state after remediation", "type": "string" }, "recurrence_outcome_event_count": { "title": "Event count in recurrence measurement window", "type": "integer" }, "recurrence_outcome_window_end": { "format": "date-time", "title": "End of recurrence measurement window", "type": "string" }, "recurrence_outcome_window_start": { "format": "date-time", "title": "Start of recurrence measurement window", "type": "string" }, "rejection_reason": { "title": "Free-text reason on reject", "type": "string" }, "root_cause_hypotheses": { "description": "Structured root-cause hypotheses", "items": { "properties": { "contribution": { "format": "decimal", "type": "string" }, "kind": { "enum": [ "equipment_malfunction", "maintenance_overdue", "supply_shortage", "staffing_shortage", "training_gap", "process_gap", "scheduling_conflict", "supplier_quality_issue", "seasonal_event", "external_event", "data_quality_issue", "unknown" ], "type": "string" }, "narrative_text": { "type": "string" } }, "required": [ "kind", "narrative_text", "contribution" ], "type": "object" }, "title": "Service recovery pattern root cause hypotheses", "type": "array" }, "severity_band": { "enum": [ "low", "medium", "high", "critical" ], "title": "Operator-facing severity band", "type": "string" }, "severity_score": { "format": "decimal", "title": "Optional calibrated severity score [0, 1]", "type": "string" }, "subject_id": { "title": "Opaque id of the operational subject within the property", "type": "string" }, "subject_kind": { "enum": [ "failure_category_hotspot", "venue_hotspot", "room_or_floor_hotspot", "time_window_hotspot", "staff_role_hotspot", "cross_signal_correlation", "comp_authority_breach_spike", "lineup_cadence_drift", "recognition_failure_against_philosophy", "recovery_paradox_breach" ], "title": "What operational subject the pattern clusters", "type": "string" }, "superseded_by_pattern_ref": { "format": "uuid", "title": "Newer pattern that supersedes this one", "type": "string", "x-aerandil-references": "hospitality.service_recovery_pattern" }, "vendor_id": { "title": "Detector vendor identity", "type": "string" }, "vendor_model_version": { "title": "Detector model version when exposed", "type": "string" }, "venue_ref": { "format": "uuid", "title": "Optional venue anchor when the pattern is venue-scoped", "type": "string", "x-aerandil-references": "hospitality.venue" } }, "required": [ "id", "subject_kind", "subject_id", "property_ref", "detection_window_start", "detection_window_end", "pattern_kind", "event_count", "failure_categories_observed", "vendor_id", "confidence", "recommended_remediation_kind", "issued_at", "expires_at", "decision_status", "policy_outcomes" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_recovery_pattern:read" ] } ], "summary": "Read Service recovery pattern", "tags": [ "recovery_pattern_detection" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.service_recovery_pattern/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA property-scoped recurring-service-failure pattern detected by an agent or model. The subject, evidence snapshot, hypotheses, severity, confidence, and recommended remediation are frozen at issue time. Decision, applied, escalation, rejection, supersedence, and recurrence fields mutate through explicit lifecycle actions.", "operationId": "get_hospitality_service_recovery_pattern_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.service_recovery_pattern" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_recovery_pattern:read" ] } ], "summary": "Read Service recovery pattern as of a watermark", "tags": [ "recovery_pattern_detection" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.service_recovery_pattern/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA property-scoped recurring-service-failure pattern detected by an agent or model. The subject, evidence snapshot, hypotheses, severity, confidence, and recommended remediation are frozen at issue time. Decision, applied, escalation, rejection, supersedence, and recurrence fields mutate through explicit lifecycle actions.", "operationId": "list_links_hospitality_service_recovery_pattern", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_recovery_pattern:read" ] } ], "summary": "List links of Service recovery pattern", "tags": [ "recovery_pattern_detection" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.pattern_at_property", "hospitality.link.pattern_at_room", "hospitality.link.pattern_at_venue", "hospitality.link.pattern_clusters_housekeeping_task", "hospitality.link.pattern_clusters_message_triage", "hospitality.link.pattern_clusters_pre_shift_lineup_event", "hospitality.link.pattern_clusters_recovery_event", "hospitality.link.pattern_clusters_work_order", "hospitality.link.pattern_escalated_to_staff_member", "hospitality.link.pattern_part_of_run", "hospitality.link.pattern_references_external_record", "hospitality.link.pattern_references_service_philosophy", "hospitality.link.pattern_remediation_chained_action_target", "hospitality.link.pattern_superseded_by" ] } } ] }, "/v1/object-types/hospitality.service_recovery_pattern/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA property-scoped recurring-service-failure pattern detected by an agent or model. The subject, evidence snapshot, hypotheses, severity, confidence, and recommended remediation are frozen at issue time. Decision, applied, escalation, rejection, supersedence, and recurrence fields mutate through explicit lifecycle actions.", "operationId": "traverse_hospitality_service_recovery_pattern", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.pattern_at_property", "hospitality.link.pattern_at_room", "hospitality.link.pattern_at_venue", "hospitality.link.pattern_clusters_housekeeping_task", "hospitality.link.pattern_clusters_message_triage", "hospitality.link.pattern_clusters_pre_shift_lineup_event", "hospitality.link.pattern_clusters_recovery_event", "hospitality.link.pattern_clusters_work_order", "hospitality.link.pattern_escalated_to_staff_member", "hospitality.link.pattern_part_of_run", "hospitality.link.pattern_references_external_record", "hospitality.link.pattern_references_service_philosophy", "hospitality.link.pattern_remediation_chained_action_target", "hospitality.link.pattern_superseded_by" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_recovery_pattern:read" ] } ], "summary": "Traverse from Service recovery pattern", "tags": [ "recovery_pattern_detection" ] } }, "/v1/object-types/hospitality.service_recovery_pattern/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA property-scoped recurring-service-failure pattern detected by an agent or model. The subject, evidence snapshot, hypotheses, severity, confidence, and recommended remediation are frozen at issue time. Decision, applied, escalation, rejection, supersedence, and recurrence fields mutate through explicit lifecycle actions.", "operationId": "search_hospitality_service_recovery_pattern", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "subject_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "failure_category_hotspot", "venue_hotspot", "room_or_floor_hotspot", "time_window_hotspot", "staff_role_hotspot", "cross_signal_correlation", "comp_authority_breach_spike", "lineup_cadence_drift", "recognition_failure_against_philosophy", "recovery_paradox_breach" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "subject_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "subject_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "subject_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "subject_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "property_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.property" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "venue_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.venue" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "detection_window_start" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "detection_window_start" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "detection_window_start" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "detection_window_end" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "detection_window_end" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "detection_window_end" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "pattern_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "recurring_failure_category", "venue_hotspot", "room_or_floor_hotspot", "time_window_hotspot", "staff_role_hotspot", "cross_signal_correlation", "comp_authority_breach_spike", "lineup_cadence_drift", "recognition_failure_against_philosophy", "recovery_paradox_breach", "follow_up_completion_drop", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "event_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "event_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "event_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "severity_band" }, "type": { "const": "eq" }, "value": { "enum": [ "low", "medium", "high", "critical" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "severity_score" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "severity_score" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "severity_score" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "failure_categories_observed" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "staff_interaction", "room_condition", "fnb_quality", "fnb_service_pace", "billing", "allergy_dietary", "security_safety", "check_in_out", "maintenance", "recognition_failure", "anticipation_miss", "noise", "temperature", "other" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "failure_subject_themes" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor_model_version" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor_model_version" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor_model_version" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "vendor_model_version" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confidence" }, "type": { "const": "eq" }, "value": { "enum": [ "low", "medium", "high" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confidence_score" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confidence_score" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "confidence_score" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "factors_considered" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "recovery_event_density", "recovery_event_severity_distribution", "recovery_event_temporal_clustering", "recovery_event_venue_clustering", "recovery_event_room_clustering", "comp_amount_distribution", "recovery_process_stages_completion_rate", "interactional_quality_distribution", "time_to_resolution_distribution", "pre_shift_lineup_cadence", "message_triage_complaint_density", "work_order_recurrence", "housekeeping_task_defect_rate", "review_sentiment_trend", "philosophy_axis_contradiction", "recovery_paradox_signal", "staff_member_turnover", "other" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "root_cause_hypotheses" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "contribution": { "format": "decimal", "type": "string" }, "kind": { "enum": [ "equipment_malfunction", "maintenance_overdue", "supply_shortage", "staffing_shortage", "training_gap", "process_gap", "scheduling_conflict", "supplier_quality_issue", "seasonal_event", "external_event", "data_quality_issue", "unknown" ], "type": "string" }, "narrative_text": { "type": "string" } }, "required": [ "kind", "narrative_text", "contribution" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_remediation_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "chain_typed_action", "schedule_capital_expenditure_review", "escalate_to_staff", "philosophy_revisit", "continue_monitoring", "cross_property_review", "update_service_register", "no_action_recommended", "update_recovery_toolkit", "data_quality_followup", "schedule_staff_training", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_remediation_action_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_remediation_action_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_remediation_action_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_remediation_action_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommended_remediation_params" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rationale_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rationale_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "pattern_context_snapshot" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issued_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decision_status" }, "type": { "const": "eq" }, "value": { "enum": [ "suggested", "applied", "rejected", "escalated", "expired", "superseded" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "decided_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_remediation_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "work_order_created", "recovery_toolkit_updated", "service_register_updated", "staff_training_referred", "engineering_referred", "supply_chain_referred", "philosophy_revisited", "lineup_cadence_corrected", "manual_intervention", "no_action_applied" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_action_correlation_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_action_correlation_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_action_correlation_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "applied_action_correlation_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "escalation_reason" }, "type": { "const": "eq" }, "value": { "enum": [ "high_severity", "capital_expenditure_required", "safety_health_concern", "training_program_redesign_needed", "regulatory_concern", "cross_property_pattern", "repeat_unresolved", "low_confidence", "manual_review_required", "operator_override" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "escalation_target_staff_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.staff_member" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejection_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rejection_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "superseded_by_pattern_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.service_recovery_pattern" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "policy_outcomes" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "gdpr_art22_explanation_required", "eu_ai_act_high_risk_processing", "ccpa_admt_notice_required", "health_safety_referral", "gdpr_art9_special_category_present", "privacy_redaction_applied", "ccpa_admt_significant_decision", "capex_threshold_breached", "none" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recurrence_outcome" }, "type": { "const": "eq" }, "value": { "enum": [ "decayed_to_zero", "decayed_significantly", "decayed_partially", "unchanged", "worsened", "not_measurable" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recurrence_outcome_window_start" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recurrence_outcome_window_start" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recurrence_outcome_window_start" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recurrence_outcome_window_end" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recurrence_outcome_window_end" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recurrence_outcome_window_end" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recurrence_outcome_event_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recurrence_outcome_event_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recurrence_outcome_event_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "pattern_payload_hash" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "pattern_payload_hash" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "pattern_payload_hash" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "pattern_payload_hash" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "subject_kind", "subject_id", "detection_window_start", "detection_window_end", "pattern_kind", "event_count", "severity_band", "severity_score", "vendor_id", "vendor_model_version", "confidence", "confidence_score", "recommended_remediation_kind", "recommended_remediation_action_ref", "rationale_text", "issued_at", "expires_at", "decision_status", "decided_at", "decided_by", "applied_remediation_kind", "applied_action_correlation_id", "escalation_reason", "rejection_reason", "recurrence_outcome", "recurrence_outcome_window_start", "recurrence_outcome_window_end", "recurrence_outcome_event_count", "pattern_payload_hash" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_recovery_pattern" }, "properties": { "additionalProperties": false, "properties": { "applied_action_correlation_id": { "title": "Correlation id of host-orchestrated chained remediation", "type": "string" }, "applied_remediation_kind": { "enum": [ "work_order_created", "recovery_toolkit_updated", "service_register_updated", "staff_training_referred", "engineering_referred", "supply_chain_referred", "philosophy_revisited", "lineup_cadence_corrected", "manual_intervention", "no_action_applied" ], "title": "Remediation class actually applied", "type": "string" }, "confidence": { "enum": [ "low", "medium", "high" ], "title": "Operator-facing confidence ordinal", "type": "string" }, "confidence_score": { "format": "decimal", "title": "Optional calibrated confidence score [0, 1]", "type": "string" }, "decided_at": { "format": "date-time", "title": "When the pattern left suggested state", "type": "string" }, "decided_by": { "title": "stable_id of the deciding principal", "type": "string" }, "decision_status": { "enum": [ "suggested", "applied", "rejected", "escalated", "expired", "superseded" ], "title": "Lifecycle state", "type": "string" }, "detection_window_end": { "format": "date-time", "title": "End of the frozen detection window", "type": "string" }, "detection_window_start": { "format": "date-time", "title": "Start of the frozen detection window", "type": "string" }, "escalation_reason": { "enum": [ "high_severity", "capital_expenditure_required", "safety_health_concern", "training_program_redesign_needed", "regulatory_concern", "cross_property_pattern", "repeat_unresolved", "low_confidence", "manual_review_required", "operator_override" ], "title": "Reason recorded on escalation", "type": "string" }, "escalation_target_staff_ref": { "format": "uuid", "title": "Optional named staff member assigned on escalation", "type": "string", "x-aerandil-references": "hospitality.staff_member" }, "event_count": { "title": "Number of clustered events", "type": "integer" }, "expires_at": { "format": "date-time", "title": "Expiry time", "type": "string" }, "factors_considered": { "items": { "enum": [ "recovery_event_density", "recovery_event_severity_distribution", "recovery_event_temporal_clustering", "recovery_event_venue_clustering", "recovery_event_room_clustering", "comp_amount_distribution", "recovery_process_stages_completion_rate", "interactional_quality_distribution", "time_to_resolution_distribution", "pre_shift_lineup_cadence", "message_triage_complaint_density", "work_order_recurrence", "housekeeping_task_defect_rate", "review_sentiment_trend", "philosophy_axis_contradiction", "recovery_paradox_signal", "staff_member_turnover", "other" ], "type": "string" }, "title": "Signals considered by the detector", "type": "array" }, "failure_categories_observed": { "items": { "enum": [ "staff_interaction", "room_condition", "fnb_quality", "fnb_service_pace", "billing", "allergy_dietary", "security_safety", "check_in_out", "maintenance", "recognition_failure", "anticipation_miss", "noise", "temperature", "other" ], "type": "string" }, "title": "Observed service-failure categories", "type": "array" }, "failure_subject_themes": { "items": { "type": "string" }, "title": "Free-text theme labels for the clustered subject", "type": "array" }, "id": { "title": "Pattern id", "type": "string" }, "issued_at": { "format": "date-time", "title": "Issue time", "type": "string" }, "pattern_context_snapshot": { "title": "Frozen context snapshot captured at issue time" }, "pattern_kind": { "enum": [ "recurring_failure_category", "venue_hotspot", "room_or_floor_hotspot", "time_window_hotspot", "staff_role_hotspot", "cross_signal_correlation", "comp_authority_breach_spike", "lineup_cadence_drift", "recognition_failure_against_philosophy", "recovery_paradox_breach", "follow_up_completion_drop", "other" ], "title": "Detected pattern class", "type": "string" }, "pattern_payload_hash": { "title": "Optional SHA-256 of canonical detector payload", "type": "string" }, "policy_outcomes": { "items": { "enum": [ "gdpr_art22_explanation_required", "eu_ai_act_high_risk_processing", "ccpa_admt_notice_required", "health_safety_referral", "gdpr_art9_special_category_present", "privacy_redaction_applied", "ccpa_admt_significant_decision", "capex_threshold_breached", "none" ], "type": "string" }, "title": "Compliance and operational policy flags observed during detection", "type": "array" }, "property_ref": { "format": "uuid", "title": "Property anchor for the pattern", "type": "string", "x-aerandil-references": "hospitality.property" }, "rationale_text": { "title": "Human-readable explanation", "type": "string" }, "recommended_remediation_action_ref": { "title": "API name of the host-orchestrated chained action, when applicable", "type": "string" }, "recommended_remediation_kind": { "enum": [ "chain_typed_action", "schedule_capital_expenditure_review", "escalate_to_staff", "philosophy_revisit", "continue_monitoring", "cross_property_review", "update_service_register", "no_action_recommended", "update_recovery_toolkit", "data_quality_followup", "schedule_staff_training", "other" ], "title": "Recommended remediation class", "type": "string" }, "recommended_remediation_params": { "title": "Proposed chained-action parameters or workflow payload" }, "recurrence_outcome": { "enum": [ "decayed_to_zero", "decayed_significantly", "decayed_partially", "unchanged", "worsened", "not_measurable" ], "title": "Observed recurrence state after remediation", "type": "string" }, "recurrence_outcome_event_count": { "title": "Event count in recurrence measurement window", "type": "integer" }, "recurrence_outcome_window_end": { "format": "date-time", "title": "End of recurrence measurement window", "type": "string" }, "recurrence_outcome_window_start": { "format": "date-time", "title": "Start of recurrence measurement window", "type": "string" }, "rejection_reason": { "title": "Free-text reason on reject", "type": "string" }, "root_cause_hypotheses": { "description": "Structured root-cause hypotheses", "items": { "properties": { "contribution": { "format": "decimal", "type": "string" }, "kind": { "enum": [ "equipment_malfunction", "maintenance_overdue", "supply_shortage", "staffing_shortage", "training_gap", "process_gap", "scheduling_conflict", "supplier_quality_issue", "seasonal_event", "external_event", "data_quality_issue", "unknown" ], "type": "string" }, "narrative_text": { "type": "string" } }, "required": [ "kind", "narrative_text", "contribution" ], "type": "object" }, "title": "Service recovery pattern root cause hypotheses", "type": "array" }, "severity_band": { "enum": [ "low", "medium", "high", "critical" ], "title": "Operator-facing severity band", "type": "string" }, "severity_score": { "format": "decimal", "title": "Optional calibrated severity score [0, 1]", "type": "string" }, "subject_id": { "title": "Opaque id of the operational subject within the property", "type": "string" }, "subject_kind": { "enum": [ "failure_category_hotspot", "venue_hotspot", "room_or_floor_hotspot", "time_window_hotspot", "staff_role_hotspot", "cross_signal_correlation", "comp_authority_breach_spike", "lineup_cadence_drift", "recognition_failure_against_philosophy", "recovery_paradox_breach" ], "title": "What operational subject the pattern clusters", "type": "string" }, "superseded_by_pattern_ref": { "format": "uuid", "title": "Newer pattern that supersedes this one", "type": "string", "x-aerandil-references": "hospitality.service_recovery_pattern" }, "vendor_id": { "title": "Detector vendor identity", "type": "string" }, "vendor_model_version": { "title": "Detector model version when exposed", "type": "string" }, "venue_ref": { "format": "uuid", "title": "Optional venue anchor when the pattern is venue-scoped", "type": "string", "x-aerandil-references": "hospitality.venue" } }, "required": [ "id", "subject_kind", "subject_id", "property_ref", "detection_window_start", "detection_window_end", "pattern_kind", "event_count", "failure_categories_observed", "vendor_id", "confidence", "recommended_remediation_kind", "issued_at", "expires_at", "decision_status", "policy_outcomes" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_recovery_pattern:read" ] } ], "summary": "Search Service recovery pattern", "tags": [ "recovery_pattern_detection" ] } }, "/v1/object-types/hospitality.service_register/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe register dialect that applies inside a specific venue — front-desk discreet-professional, signature-restaurant formal-warm, cocktail-bar crafted-theatre, spa focused-coaching. Inherits unstated axes from the property's `service_philosophy` defaults (the philosophy's `*_default` fields seed the register's matching fields when a venue-scoped override isn't recorded). When Tier 1.4 lands, the register may inherit from a `venue_brand` instead; the Property → Venue inheritance is fine for §1.2 alone (proposal §10 open question 7).", "operationId": "get_hospitality_service_register", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_register" }, "properties": { "additionalProperties": false, "properties": { "address_form": { "enum": [ "mr_ms", "first_name", "no_name" ], "title": "Address form", "type": "string" }, "body_language_norm": { "enum": [ "formal_distance", "warm_proximity", "crafted_theatre", "discreet_invisible" ], "title": "Body language norm", "type": "string" }, "id": { "title": "Register id", "type": "string" }, "personality_presentation": { "enum": [ "muted", "forward", "as_product" ], "title": "Personality presentation", "type": "string" }, "recommendation_style": { "enum": [ "instructive", "suggestive", "consultative", "silent_unless_asked" ], "title": "Recommendation style", "type": "string" }, "register_spec_text": { "title": "Register narrative", "type": "string" }, "speech_rhythm": { "enum": [ "clipped", "measured", "flowing", "theatrical" ], "title": "Speech rhythm", "type": "string" }, "surface_register": { "enum": [ "formal_warm", "crafted_theatre", "quick_warm", "discreet_professional", "focused_coaching", "other" ], "title": "Surface register", "type": "string" } }, "required": [ "id" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_register:read" ] } ], "summary": "Read Service register", "tags": [ "service_philosophy" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.service_register/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe register dialect that applies inside a specific venue — front-desk discreet-professional, signature-restaurant formal-warm, cocktail-bar crafted-theatre, spa focused-coaching. Inherits unstated axes from the property's `service_philosophy` defaults (the philosophy's `*_default` fields seed the register's matching fields when a venue-scoped override isn't recorded). When Tier 1.4 lands, the register may inherit from a `venue_brand` instead; the Property → Venue inheritance is fine for §1.2 alone (proposal §10 open question 7).", "operationId": "get_hospitality_service_register_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.service_register" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_register:read" ] } ], "summary": "Read Service register as of a watermark", "tags": [ "service_philosophy" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.service_register/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe register dialect that applies inside a specific venue — front-desk discreet-professional, signature-restaurant formal-warm, cocktail-bar crafted-theatre, spa focused-coaching. Inherits unstated axes from the property's `service_philosophy` defaults (the philosophy's `*_default` fields seed the register's matching fields when a venue-scoped override isn't recorded). When Tier 1.4 lands, the register may inherit from a `venue_brand` instead; the Property → Venue inheritance is fine for §1.2 alone (proposal §10 open question 7).", "operationId": "list_links_hospitality_service_register", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_register:read" ] } ], "summary": "List links of Service register", "tags": [ "service_philosophy" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.venue_has_register" ] } } ] }, "/v1/object-types/hospitality.service_register/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe register dialect that applies inside a specific venue — front-desk discreet-professional, signature-restaurant formal-warm, cocktail-bar crafted-theatre, spa focused-coaching. Inherits unstated axes from the property's `service_philosophy` defaults (the philosophy's `*_default` fields seed the register's matching fields when a venue-scoped override isn't recorded). When Tier 1.4 lands, the register may inherit from a `venue_brand` instead; the Property → Venue inheritance is fine for §1.2 alone (proposal §10 open question 7).", "operationId": "traverse_hospitality_service_register", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.venue_has_register" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_register:read" ] } ], "summary": "Traverse from Service register", "tags": [ "service_philosophy" ] } }, "/v1/object-types/hospitality.service_register/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe register dialect that applies inside a specific venue — front-desk discreet-professional, signature-restaurant formal-warm, cocktail-bar crafted-theatre, spa focused-coaching. Inherits unstated axes from the property's `service_philosophy` defaults (the philosophy's `*_default` fields seed the register's matching fields when a venue-scoped override isn't recorded). When Tier 1.4 lands, the register may inherit from a `venue_brand` instead; the Property → Venue inheritance is fine for §1.2 alone (proposal §10 open question 7).", "operationId": "search_hospitality_service_register", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "surface_register" }, "type": { "const": "eq" }, "value": { "enum": [ "formal_warm", "crafted_theatre", "quick_warm", "discreet_professional", "focused_coaching", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "address_form" }, "type": { "const": "eq" }, "value": { "enum": [ "mr_ms", "first_name", "no_name" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "speech_rhythm" }, "type": { "const": "eq" }, "value": { "enum": [ "clipped", "measured", "flowing", "theatrical" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recommendation_style" }, "type": { "const": "eq" }, "value": { "enum": [ "instructive", "suggestive", "consultative", "silent_unless_asked" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "personality_presentation" }, "type": { "const": "eq" }, "value": { "enum": [ "muted", "forward", "as_product" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "body_language_norm" }, "type": { "const": "eq" }, "value": { "enum": [ "formal_distance", "warm_proximity", "crafted_theatre", "discreet_invisible" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "register_spec_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "register_spec_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "surface_register", "address_form", "speech_rhythm", "recommendation_style", "personality_presentation", "body_language_norm", "register_spec_text" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_register" }, "properties": { "additionalProperties": false, "properties": { "address_form": { "enum": [ "mr_ms", "first_name", "no_name" ], "title": "Address form", "type": "string" }, "body_language_norm": { "enum": [ "formal_distance", "warm_proximity", "crafted_theatre", "discreet_invisible" ], "title": "Body language norm", "type": "string" }, "id": { "title": "Register id", "type": "string" }, "personality_presentation": { "enum": [ "muted", "forward", "as_product" ], "title": "Personality presentation", "type": "string" }, "recommendation_style": { "enum": [ "instructive", "suggestive", "consultative", "silent_unless_asked" ], "title": "Recommendation style", "type": "string" }, "register_spec_text": { "title": "Register narrative", "type": "string" }, "speech_rhythm": { "enum": [ "clipped", "measured", "flowing", "theatrical" ], "title": "Speech rhythm", "type": "string" }, "surface_register": { "enum": [ "formal_warm", "crafted_theatre", "quick_warm", "discreet_professional", "focused_coaching", "other" ], "title": "Surface register", "type": "string" } }, "required": [ "id" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_register:read" ] } ], "summary": "Search Service register", "tags": [ "service_philosophy" ] } }, "/v1/object-types/hospitality.service_table/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA seatable unit within a service area — table, booth, bar-stool group. Carries capacity, a stable label, and an x/y position for the floor-plan render. Status follows the industry floor vocabulary: open_check seats it, settle_check marks it dirty, and dirty → available is a bussing update on the CRUD surface.", "operationId": "get_hospitality_service_table", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_table" }, "properties": { "additionalProperties": false, "properties": { "capacity": { "title": "Seats", "type": "integer" }, "label": { "title": "Table label", "type": "string" }, "position_x": { "format": "decimal", "title": "Floor-plan x position", "type": "string" }, "position_y": { "format": "decimal", "title": "Floor-plan y position", "type": "string" }, "status": { "enum": [ "available", "seated", "dirty", "reserved", "blocked" ], "title": "Floor status", "type": "string" } }, "required": [ "label", "capacity", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_table:read" ] } ], "summary": "Read Service table", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.service_table/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA seatable unit within a service area — table, booth, bar-stool group. Carries capacity, a stable label, and an x/y position for the floor-plan render. Status follows the industry floor vocabulary: open_check seats it, settle_check marks it dirty, and dirty → available is a bussing update on the CRUD surface.", "operationId": "get_hospitality_service_table_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.service_table" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_table:read" ] } ], "summary": "Read Service table as of a watermark", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.service_table/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA seatable unit within a service area — table, booth, bar-stool group. Carries capacity, a stable label, and an x/y position for the floor-plan render. Status follows the industry floor vocabulary: open_check seats it, settle_check marks it dirty, and dirty → available is a bussing update on the CRUD surface.", "operationId": "list_links_hospitality_service_table", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_table:read" ] } ], "summary": "List links of Service table", "tags": [ "fnb" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.check_opened_at_table", "hospitality.link.service_table_in_area" ] } } ] }, "/v1/object-types/hospitality.service_table/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA seatable unit within a service area — table, booth, bar-stool group. Carries capacity, a stable label, and an x/y position for the floor-plan render. Status follows the industry floor vocabulary: open_check seats it, settle_check marks it dirty, and dirty → available is a bussing update on the CRUD surface.", "operationId": "traverse_hospitality_service_table", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.check_opened_at_table", "hospitality.link.service_table_in_area" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_table:read" ] } ], "summary": "Traverse from Service table", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.service_table/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA seatable unit within a service area — table, booth, bar-stool group. Carries capacity, a stable label, and an x/y position for the floor-plan render. Status follows the industry floor vocabulary: open_check seats it, settle_check marks it dirty, and dirty → available is a bussing update on the CRUD surface.", "operationId": "search_hospitality_service_table", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "label" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "label" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "label" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "label" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "capacity" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "capacity" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "capacity" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "available", "seated", "dirty", "reserved", "blocked" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "position_x" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "position_x" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "position_x" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "position_y" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "position_y" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "position_y" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "label", "capacity", "status", "position_x", "position_y" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.service_table" }, "properties": { "additionalProperties": false, "properties": { "capacity": { "title": "Seats", "type": "integer" }, "label": { "title": "Table label", "type": "string" }, "position_x": { "format": "decimal", "title": "Floor-plan x position", "type": "string" }, "position_y": { "format": "decimal", "title": "Floor-plan y position", "type": "string" }, "status": { "enum": [ "available", "seated", "dirty", "reserved", "blocked" ], "title": "Floor status", "type": "string" } }, "required": [ "label", "capacity", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.service_table:read" ] } ], "summary": "Search Service table", "tags": [ "fnb" ] } }, "/v1/object-types/hospitality.share_group/objects/{id}": { "get": { "description": "Read an existing instance.\n\nTwo or more reservations sharing one physical room, each with its own account (OPERA's share). One room-night is deducted per covered date regardless of member count; members check in and out independently. Distribution `full` keeps every member's booked rates; `split` divides the primary's rate per shared night (remainder to the joiner). Terminal status `separated` re-establishes the members as independent reservations, re-consuming their availability with a live sellability check.", "operationId": "get_hospitality_share_group", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.share_group" }, "properties": { "additionalProperties": false, "properties": { "combined_at": { "format": "date-time", "title": "Combined at", "type": "string" }, "distribution": { "enum": [ "full", "split" ], "title": "Rate distribution", "type": "string" }, "id": { "title": "Share group id", "type": "string" }, "primary_reservation_ref": { "format": "uuid", "title": "Primary reservation", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "separated_at": { "format": "date-time", "title": "Separated at", "type": "string" }, "status": { "enum": [ "active", "separated" ], "title": "Status", "type": "string" } }, "required": [ "id", "status", "distribution", "primary_reservation_ref", "combined_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.share_group:read" ] } ], "summary": "Read Share group", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.share_group/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nTwo or more reservations sharing one physical room, each with its own account (OPERA's share). One room-night is deducted per covered date regardless of member count; members check in and out independently. Distribution `full` keeps every member's booked rates; `split` divides the primary's rate per shared night (remainder to the joiner). Terminal status `separated` re-establishes the members as independent reservations, re-consuming their availability with a live sellability check.", "operationId": "get_hospitality_share_group_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.share_group" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.share_group:read" ] } ], "summary": "Read Share group as of a watermark", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.share_group/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nTwo or more reservations sharing one physical room, each with its own account (OPERA's share). One room-night is deducted per covered date regardless of member count; members check in and out independently. Distribution `full` keeps every member's booked rates; `split` divides the primary's rate per shared night (remainder to the joiner). Terminal status `separated` re-establishes the members as independent reservations, re-consuming their availability with a live sellability check.", "operationId": "list_links_hospitality_share_group", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.share_group:read" ] } ], "summary": "List links of Share group", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.reservation_in_share_group", "hospitality.link.share_group_at_property" ] } } ] }, "/v1/object-types/hospitality.share_group/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nTwo or more reservations sharing one physical room, each with its own account (OPERA's share). One room-night is deducted per covered date regardless of member count; members check in and out independently. Distribution `full` keeps every member's booked rates; `split` divides the primary's rate per shared night (remainder to the joiner). Terminal status `separated` re-establishes the members as independent reservations, re-consuming their availability with a live sellability check.", "operationId": "traverse_hospitality_share_group", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.reservation_in_share_group", "hospitality.link.share_group_at_property" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.share_group:read" ] } ], "summary": "Traverse from Share group", "tags": [ "booking" ] } }, "/v1/object-types/hospitality.share_group/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nTwo or more reservations sharing one physical room, each with its own account (OPERA's share). One room-night is deducted per covered date regardless of member count; members check in and out independently. Distribution `full` keeps every member's booked rates; `split` divides the primary's rate per shared night (remainder to the joiner). Terminal status `separated` re-establishes the members as independent reservations, re-consuming their availability with a live sellability check.", "operationId": "search_hospitality_share_group", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "separated" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "distribution" }, "type": { "const": "eq" }, "value": { "enum": [ "full", "split" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "primary_reservation_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.reservation" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "combined_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "combined_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "combined_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "separated_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "separated_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "separated_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "status", "distribution", "combined_at", "separated_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.share_group" }, "properties": { "additionalProperties": false, "properties": { "combined_at": { "format": "date-time", "title": "Combined at", "type": "string" }, "distribution": { "enum": [ "full", "split" ], "title": "Rate distribution", "type": "string" }, "id": { "title": "Share group id", "type": "string" }, "primary_reservation_ref": { "format": "uuid", "title": "Primary reservation", "type": "string", "x-aerandil-references": "hospitality.reservation" }, "separated_at": { "format": "date-time", "title": "Separated at", "type": "string" }, "status": { "enum": [ "active", "separated" ], "title": "Status", "type": "string" } }, "required": [ "id", "status", "distribution", "primary_reservation_ref", "combined_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.share_group:read" ] } ], "summary": "Search Share group", "tags": [ "booking" ] } }, "/v1/object-types/hospitality.spa_service/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA bookable treatment offering: price, service duration, and the provider-blocking buffer pair — pre time (room setup) and clean-up time (turnover) — that every major spa system models (Book4Time Pre Time / Clean-up Time, Zenoti recovery_time, Mindbody PrepTime / FinishTime). All three are snapshotted onto the appointment at booking, so catalogue edits never rewrite booking history. Distinct from `service_item` (POS catalogue row, no duration or resourcing) and from `wellness_modality` (taxonomy + licensing, proposal 0005) — the optional spa_service_for_modality link carries the clinical-licensing gate into book_appointment.", "operationId": "get_hospitality_spa_service", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.spa_service" }, "properties": { "additionalProperties": false, "properties": { "active": { "title": "Bookable", "type": "boolean" }, "cleanup_time_minutes": { "title": "Provider-blocking turnover time after the service (linen / sanitise)", "type": "integer" }, "code": { "title": "Service code", "type": "string" }, "couples": { "title": "Couples service (two guests, one capacity-2 room, two appointments)", "type": "boolean" }, "description": { "title": "Guest-facing description", "type": "string" }, "duration_minutes": { "title": "Service duration in minutes (guest-facing treatment time)", "type": "integer" }, "kind": { "enum": [ "massage", "facial", "body_treatment", "nail", "hair", "hydrotherapy", "wellness_session", "other" ], "title": "Treatment taxonomy (ISPA / CBRE reporting mix)", "type": "string" }, "name": { "title": "Service name", "type": "string" }, "pre_time_minutes": { "title": "Provider-blocking setup time before the service (room prep)", "type": "integer" }, "price": { "description": "List price (snapshotted onto the appointment at booking)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Spa service price", "type": "object" } }, "required": [ "code", "name", "kind", "price", "duration_minutes", "pre_time_minutes", "cleanup_time_minutes", "couples", "active" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.spa_service:read" ] } ], "summary": "Read Spa service", "tags": [ "spa" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.spa_service/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA bookable treatment offering: price, service duration, and the provider-blocking buffer pair — pre time (room setup) and clean-up time (turnover) — that every major spa system models (Book4Time Pre Time / Clean-up Time, Zenoti recovery_time, Mindbody PrepTime / FinishTime). All three are snapshotted onto the appointment at booking, so catalogue edits never rewrite booking history. Distinct from `service_item` (POS catalogue row, no duration or resourcing) and from `wellness_modality` (taxonomy + licensing, proposal 0005) — the optional spa_service_for_modality link carries the clinical-licensing gate into book_appointment.", "operationId": "get_hospitality_spa_service_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.spa_service" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.spa_service:read" ] } ], "summary": "Read Spa service as of a watermark", "tags": [ "spa" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.spa_service/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA bookable treatment offering: price, service duration, and the provider-blocking buffer pair — pre time (room setup) and clean-up time (turnover) — that every major spa system models (Book4Time Pre Time / Clean-up Time, Zenoti recovery_time, Mindbody PrepTime / FinishTime). All three are snapshotted onto the appointment at booking, so catalogue edits never rewrite booking history. Distinct from `service_item` (POS catalogue row, no duration or resourcing) and from `wellness_modality` (taxonomy + licensing, proposal 0005) — the optional spa_service_for_modality link carries the clinical-licensing gate into book_appointment.", "operationId": "list_links_hospitality_spa_service", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.spa_service:read" ] } ], "summary": "List links of Spa service", "tags": [ "spa" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.appointment_for_service", "hospitality.link.spa_service_for_modality", "hospitality.link.staff_performs_spa_service", "hospitality.link.treatment_room_supports_service" ] } } ] }, "/v1/object-types/hospitality.spa_service/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA bookable treatment offering: price, service duration, and the provider-blocking buffer pair — pre time (room setup) and clean-up time (turnover) — that every major spa system models (Book4Time Pre Time / Clean-up Time, Zenoti recovery_time, Mindbody PrepTime / FinishTime). All three are snapshotted onto the appointment at booking, so catalogue edits never rewrite booking history. Distinct from `service_item` (POS catalogue row, no duration or resourcing) and from `wellness_modality` (taxonomy + licensing, proposal 0005) — the optional spa_service_for_modality link carries the clinical-licensing gate into book_appointment.", "operationId": "traverse_hospitality_spa_service", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.appointment_for_service", "hospitality.link.spa_service_for_modality", "hospitality.link.staff_performs_spa_service", "hospitality.link.treatment_room_supports_service" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.spa_service:read" ] } ], "summary": "Traverse from Spa service", "tags": [ "spa" ] } }, "/v1/object-types/hospitality.spa_service/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA bookable treatment offering: price, service duration, and the provider-blocking buffer pair — pre time (room setup) and clean-up time (turnover) — that every major spa system models (Book4Time Pre Time / Clean-up Time, Zenoti recovery_time, Mindbody PrepTime / FinishTime). All three are snapshotted onto the appointment at booking, so catalogue edits never rewrite booking history. Distinct from `service_item` (POS catalogue row, no duration or resourcing) and from `wellness_modality` (taxonomy + licensing, proposal 0005) — the optional spa_service_for_modality link carries the clinical-licensing gate into book_appointment.", "operationId": "search_hospitality_spa_service", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "massage", "facial", "body_treatment", "nail", "hair", "hydrotherapy", "wellness_session", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "price" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "duration_minutes" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "duration_minutes" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "duration_minutes" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "pre_time_minutes" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "pre_time_minutes" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "pre_time_minutes" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cleanup_time_minutes" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cleanup_time_minutes" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cleanup_time_minutes" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "couples" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "active" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "kind", "duration_minutes", "pre_time_minutes", "cleanup_time_minutes", "description" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.spa_service" }, "properties": { "additionalProperties": false, "properties": { "active": { "title": "Bookable", "type": "boolean" }, "cleanup_time_minutes": { "title": "Provider-blocking turnover time after the service (linen / sanitise)", "type": "integer" }, "code": { "title": "Service code", "type": "string" }, "couples": { "title": "Couples service (two guests, one capacity-2 room, two appointments)", "type": "boolean" }, "description": { "title": "Guest-facing description", "type": "string" }, "duration_minutes": { "title": "Service duration in minutes (guest-facing treatment time)", "type": "integer" }, "kind": { "enum": [ "massage", "facial", "body_treatment", "nail", "hair", "hydrotherapy", "wellness_session", "other" ], "title": "Treatment taxonomy (ISPA / CBRE reporting mix)", "type": "string" }, "name": { "title": "Service name", "type": "string" }, "pre_time_minutes": { "title": "Provider-blocking setup time before the service (room prep)", "type": "integer" }, "price": { "description": "List price (snapshotted onto the appointment at booking)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Spa service price", "type": "object" } }, "required": [ "code", "name", "kind", "price", "duration_minutes", "pre_time_minutes", "cleanup_time_minutes", "couples", "active" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.spa_service:read" ] } ], "summary": "Search Spa service", "tags": [ "spa" ] } }, "/v1/object-types/hospitality.staff_certification/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA credential grant held by a staff member — the certification kind, issuing authority, issue / expiry dates, and a verification sign-off. Renewals append a new grant; the current one is the latest non-revoked, non-expired row of its kind.", "operationId": "get_hospitality_staff_certification", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_certification" }, "properties": { "additionalProperties": false, "properties": { "credential_reference": { "title": "Certificate / badge number", "type": "string" }, "expiry_date": { "format": "date", "title": "Expiry date (null = non-expiring)", "type": "string" }, "id": { "title": "Certification id", "type": "string" }, "issue_date": { "format": "date", "title": "Issue date", "type": "string" }, "issuing_authority": { "title": "Issuing authority (e.g. ServSafe, WSET)", "type": "string" }, "kind": { "enum": [ "food_safety_manager", "food_safety_handler", "allergen_awareness", "alcohol_service", "haccp", "sommelier", "wset", "first_aid", "cpr", "pool_lifeguard", "massage_therapy_license", "cosmetology_license", "fire_safety", "other" ], "title": "Certification kind", "type": "string" }, "revoked_at": { "format": "date", "title": "Revoked at (null = active)", "type": "string" }, "revoked_reason": { "title": "Revocation reason", "type": "string" }, "verification_status": { "enum": [ "self_reported", "document_on_file", "verified" ], "title": "Verification status", "type": "string" }, "verified_at": { "format": "date-time", "title": "Verified at", "type": "string" }, "verified_by": { "title": "Verifier (staff principal)", "type": "string" } }, "required": [ "id", "verification_status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.staff_certification:read" ] } ], "summary": "Read Staff certification", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.staff_certification/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA credential grant held by a staff member — the certification kind, issuing authority, issue / expiry dates, and a verification sign-off. Renewals append a new grant; the current one is the latest non-revoked, non-expired row of its kind.", "operationId": "get_hospitality_staff_certification_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.staff_certification" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.staff_certification:read" ] } ], "summary": "Read Staff certification as of a watermark", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.staff_certification/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA credential grant held by a staff member — the certification kind, issuing authority, issue / expiry dates, and a verification sign-off. Renewals append a new grant; the current one is the latest non-revoked, non-expired row of its kind.", "operationId": "list_links_hospitality_staff_certification", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.staff_certification:read" ] } ], "summary": "List links of Staff certification", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.staff_certification_for_staff" ] } } ] }, "/v1/object-types/hospitality.staff_certification/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA credential grant held by a staff member — the certification kind, issuing authority, issue / expiry dates, and a verification sign-off. Renewals append a new grant; the current one is the latest non-revoked, non-expired row of its kind.", "operationId": "traverse_hospitality_staff_certification", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.staff_certification_for_staff" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.staff_certification:read" ] } ], "summary": "Traverse from Staff certification", "tags": [ "people" ] } }, "/v1/object-types/hospitality.staff_certification/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA credential grant held by a staff member — the certification kind, issuing authority, issue / expiry dates, and a verification sign-off. Renewals append a new grant; the current one is the latest non-revoked, non-expired row of its kind.", "operationId": "search_hospitality_staff_certification", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "food_safety_manager", "food_safety_handler", "allergen_awareness", "alcohol_service", "haccp", "sommelier", "wset", "first_aid", "cpr", "pool_lifeguard", "massage_therapy_license", "cosmetology_license", "fire_safety", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issuing_authority" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issuing_authority" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issuing_authority" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issuing_authority" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "credential_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "credential_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "credential_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "credential_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issue_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issue_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "issue_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expiry_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expiry_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expiry_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "verification_status" }, "type": { "const": "eq" }, "value": { "enum": [ "self_reported", "document_on_file", "verified" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "verified_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "verified_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "verified_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "verified_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "verified_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "verified_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "verified_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revoked_at" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revoked_at" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revoked_at" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revoked_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revoked_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revoked_reason" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revoked_reason" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "kind", "issuing_authority", "credential_reference", "issue_date", "expiry_date", "verification_status", "verified_by", "verified_at", "revoked_at", "revoked_reason" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_certification" }, "properties": { "additionalProperties": false, "properties": { "credential_reference": { "title": "Certificate / badge number", "type": "string" }, "expiry_date": { "format": "date", "title": "Expiry date (null = non-expiring)", "type": "string" }, "id": { "title": "Certification id", "type": "string" }, "issue_date": { "format": "date", "title": "Issue date", "type": "string" }, "issuing_authority": { "title": "Issuing authority (e.g. ServSafe, WSET)", "type": "string" }, "kind": { "enum": [ "food_safety_manager", "food_safety_handler", "allergen_awareness", "alcohol_service", "haccp", "sommelier", "wset", "first_aid", "cpr", "pool_lifeguard", "massage_therapy_license", "cosmetology_license", "fire_safety", "other" ], "title": "Certification kind", "type": "string" }, "revoked_at": { "format": "date", "title": "Revoked at (null = active)", "type": "string" }, "revoked_reason": { "title": "Revocation reason", "type": "string" }, "verification_status": { "enum": [ "self_reported", "document_on_file", "verified" ], "title": "Verification status", "type": "string" }, "verified_at": { "format": "date-time", "title": "Verified at", "type": "string" }, "verified_by": { "title": "Verifier (staff principal)", "type": "string" } }, "required": [ "id", "verification_status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.staff_certification:read" ] } ], "summary": "Search Staff certification", "tags": [ "people" ] } }, "/v1/object-types/hospitality.staff_employment_period/objects/{id}": { "get": { "description": "Read an existing instance.\n\nPer-period employment history for a staff member. The current period has null `termination_date`. Lifetime-tenure projection sums durations across all periods.", "operationId": "get_hospitality_staff_employment_period", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_employment_period" }, "properties": { "additionalProperties": false, "properties": { "hire_date": { "format": "date", "title": "Hire date", "type": "string" }, "id": { "title": "Period id", "type": "string" }, "notes": { "title": "Notes", "type": "string" }, "role_at_hire": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "Role at hire", "type": "string" }, "termination_date": { "format": "date", "title": "Termination date (null = current)", "type": "string" }, "termination_reason": { "enum": [ "voluntary", "involuntary", "retirement", "transfer", "end_of_season", "other" ], "title": "Termination reason", "type": "string" } }, "required": [ "id" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.staff_employment_period:read" ] } ], "summary": "Read Staff employment period", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.staff_employment_period/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nPer-period employment history for a staff member. The current period has null `termination_date`. Lifetime-tenure projection sums durations across all periods.", "operationId": "get_hospitality_staff_employment_period_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.staff_employment_period" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.staff_employment_period:read" ] } ], "summary": "Read Staff employment period as of a watermark", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.staff_employment_period/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nPer-period employment history for a staff member. The current period has null `termination_date`. Lifetime-tenure projection sums durations across all periods.", "operationId": "list_links_hospitality_staff_employment_period", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.staff_employment_period:read" ] } ], "summary": "List links of Staff employment period", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.staff_employment_period_for_staff" ] } } ] }, "/v1/object-types/hospitality.staff_employment_period/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nPer-period employment history for a staff member. The current period has null `termination_date`. Lifetime-tenure projection sums durations across all periods.", "operationId": "traverse_hospitality_staff_employment_period", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.staff_employment_period_for_staff" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.staff_employment_period:read" ] } ], "summary": "Traverse from Staff employment period", "tags": [ "people" ] } }, "/v1/object-types/hospitality.staff_employment_period/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nPer-period employment history for a staff member. The current period has null `termination_date`. Lifetime-tenure projection sums durations across all periods.", "operationId": "search_hospitality_staff_employment_period", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hire_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hire_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hire_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "termination_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "termination_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "termination_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "termination_reason" }, "type": { "const": "eq" }, "value": { "enum": [ "voluntary", "involuntary", "retirement", "transfer", "end_of_season", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "role_at_hire" }, "type": { "const": "eq" }, "value": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "hire_date", "termination_date", "termination_reason", "role_at_hire", "notes" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_employment_period" }, "properties": { "additionalProperties": false, "properties": { "hire_date": { "format": "date", "title": "Hire date", "type": "string" }, "id": { "title": "Period id", "type": "string" }, "notes": { "title": "Notes", "type": "string" }, "role_at_hire": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "Role at hire", "type": "string" }, "termination_date": { "format": "date", "title": "Termination date (null = current)", "type": "string" }, "termination_reason": { "enum": [ "voluntary", "involuntary", "retirement", "transfer", "end_of_season", "other" ], "title": "Termination reason", "type": "string" } }, "required": [ "id" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.staff_employment_period:read" ] } ], "summary": "Search Staff employment period", "tags": [ "people" ] } }, "/v1/object-types/hospitality.staff_member/objects/{id}": { "get": { "description": "Read an existing instance.\n\nAn employee. Linked to a property; for chains a single staff member can be a manager across multiple properties via additional links in higher-level extensions.", "operationId": "get_hospitality_staff_member", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" }, "properties": { "additionalProperties": false, "properties": { "active": { "title": "Active", "type": "boolean" }, "comp_authority_summary": { "description": "Resolved comp authority summary (cache)", "properties": { "can_comp_room_night": { "type": "boolean" }, "can_comp_spa": { "type": "boolean" }, "daily_combined_limit": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "last_computed": { "format": "date-time", "type": "string" }, "per_incident_limit": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "title": "Staff member comp authority summary", "type": "object" }, "contracted_weekly_hours": { "format": "decimal", "title": "The hours a week the staff member is contracted for (more than 0, at most 168) — what the pacing report's percentage_worked is of", "type": "string" }, "department": { "title": "Department", "type": "string" }, "discipline": { "enum": [ "front_office", "food_beverage", "culinary", "bar", "housekeeping", "engineering", "spa", "wellness_clinical", "wellness_coaching", "sales", "revenue", "management", "other" ], "title": "Discipline", "type": "string" }, "email": { "title": "Email", "type": "string" }, "employee_id": { "title": "Employee ID", "type": "string" }, "family_name": { "title": "Family name", "type": "string" }, "given_name": { "title": "Given name", "type": "string" }, "handset_passcode_hash": { "title": "Handset PIN hash (Argon2id, PHC string)", "type": "string" }, "identity_subject": { "title": "Identity-provider subject (SSO)", "type": "string" }, "most_recent_hire_date": { "format": "date", "title": "Most recent hire date", "type": "string" }, "pathway_stage_code": { "title": "Pathway stage code (operator vocabulary)", "type": "string" }, "push_topics": { "items": { "enum": [ "cleaning_tasks", "faults", "urgent_faults", "postponed_faults", "delegated_faults", "stock" ], "type": "string" }, "title": "The push topics the staff member hears; absent = cleaning_tasks and faults (the nudges every handset has had), and the fault topics (urgent, postponed, delegated) only when named", "type": "array" }, "role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "Role", "type": "string" }, "sort_preferences": { "description": "The staff member's own order for a board, one entry per board — wins over the house's pattern in `board_sort`", "items": { "properties": { "board": { "enum": [ "housekeeping_sheet", "housekeeping_rack", "work_orders", "pacing" ], "type": "string" }, "keys": { "items": { "properties": { "direction": { "enum": [ "asc", "desc" ], "type": "string" }, "key": { "enum": [ "priority", "room_number", "floor", "task_type", "status", "due_at", "credits", "arrival_time", "departure_time", "pending_credits", "target_percent", "name" ], "type": "string" }, "values": { "items": { "type": "string" }, "type": "array" } }, "required": [ "key", "direction" ], "type": "object" }, "type": "array" } }, "required": [ "board", "keys" ], "type": "object" }, "title": "Staff member sort preferences", "type": "array" }, "tenure_computed_at": { "format": "date-time", "title": "Tenure refresh timestamp", "type": "string" }, "tenure_years_at_current_property": { "format": "decimal", "title": "Tenure years at current property (projection)", "type": "string" }, "tenure_years_lifetime": { "format": "decimal", "title": "Tenure years lifetime (projection)", "type": "string" } }, "required": [ "role", "active" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.staff_member:read" ] } ], "summary": "Read Staff member", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.staff_member/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nAn employee. Linked to a property; for chains a single staff member can be a manager across multiple properties via additional links in higher-level extensions.", "operationId": "get_hospitality_staff_member_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.staff_member" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.staff_member:read" ] } ], "summary": "Read Staff member as of a watermark", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.staff_member/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nAn employee. Linked to a property; for chains a single staff member can be a manager across multiple properties via additional links in higher-level extensions.", "operationId": "list_links_hospitality_staff_member", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.staff_member:read" ] } ], "summary": "List links of Staff member", "tags": [ "people" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.appointment_with_provider", "hospitality.link.checklist_result_recorded_by", "hospitality.link.checkpoint_result_recorded_by", "hospitality.link.desk_session_acting_staff", "hospitality.link.desk_session_opened_by", "hospitality.link.fraud_assessment_escalated_to_staff_member", "hospitality.link.guest_feedback_entry_by_staff", "hospitality.link.housekeeping_briefing_by", "hospitality.link.housekeeping_task_assigned_to", "hospitality.link.housekeeping_task_entry_recorded_by", "hospitality.link.inspection_round_completed_by", "hospitality.link.inspection_round_started_by", "hospitality.link.labour_entry_for_staff_member", "hospitality.link.lost_found_item_found_by", "hospitality.link.message_triage_escalated_to_staff_member", "hospitality.link.pattern_escalated_to_staff_member", "hospitality.link.shift_for_staff_member", "hospitality.link.staff_certification_for_staff", "hospitality.link.staff_employment_period_for_staff", "hospitality.link.staff_performs_spa_service", "hospitality.link.staff_works_at_property", "hospitality.link.stock_movement_recorded_by", "hospitality.link.work_order_assigned_to", "hospitality.link.work_order_entry_recorded_by", "hospitality.link.worker_group_has_member", "hospitality.link.workflow_run_targets_staff_member" ] } } ] }, "/v1/object-types/hospitality.staff_member/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nAn employee. Linked to a property; for chains a single staff member can be a manager across multiple properties via additional links in higher-level extensions.", "operationId": "traverse_hospitality_staff_member", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.appointment_with_provider", "hospitality.link.checklist_result_recorded_by", "hospitality.link.checkpoint_result_recorded_by", "hospitality.link.desk_session_acting_staff", "hospitality.link.desk_session_opened_by", "hospitality.link.fraud_assessment_escalated_to_staff_member", "hospitality.link.guest_feedback_entry_by_staff", "hospitality.link.housekeeping_briefing_by", "hospitality.link.housekeeping_task_assigned_to", "hospitality.link.housekeeping_task_entry_recorded_by", "hospitality.link.inspection_round_completed_by", "hospitality.link.inspection_round_started_by", "hospitality.link.labour_entry_for_staff_member", "hospitality.link.lost_found_item_found_by", "hospitality.link.message_triage_escalated_to_staff_member", "hospitality.link.pattern_escalated_to_staff_member", "hospitality.link.shift_for_staff_member", "hospitality.link.staff_certification_for_staff", "hospitality.link.staff_employment_period_for_staff", "hospitality.link.staff_performs_spa_service", "hospitality.link.staff_works_at_property", "hospitality.link.stock_movement_recorded_by", "hospitality.link.work_order_assigned_to", "hospitality.link.work_order_entry_recorded_by", "hospitality.link.worker_group_has_member", "hospitality.link.workflow_run_targets_staff_member" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.staff_member:read" ] } ], "summary": "Traverse from Staff member", "tags": [ "people" ] } }, "/v1/object-types/hospitality.staff_member/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nAn employee. Linked to a property; for chains a single staff member can be a manager across multiple properties via additional links in higher-level extensions.", "operationId": "search_hospitality_staff_member", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "employee_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "employee_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "employee_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "employee_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "given_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "given_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "given_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "given_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "family_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "family_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "family_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "family_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "email" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "email" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "email" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "email" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "handset_passcode_hash" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "handset_passcode_hash" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "handset_passcode_hash" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "handset_passcode_hash" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "identity_subject" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "identity_subject" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "identity_subject" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "identity_subject" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "role" }, "type": { "const": "eq" }, "value": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "department" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "department" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "department" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "department" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "discipline" }, "type": { "const": "eq" }, "value": { "enum": [ "front_office", "food_beverage", "culinary", "bar", "housekeeping", "engineering", "spa", "wellness_clinical", "wellness_coaching", "sales", "revenue", "management", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "pathway_stage_code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "pathway_stage_code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "pathway_stage_code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "pathway_stage_code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "most_recent_hire_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "most_recent_hire_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "most_recent_hire_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tenure_years_at_current_property" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tenure_years_at_current_property" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tenure_years_at_current_property" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tenure_years_lifetime" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tenure_years_lifetime" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tenure_years_lifetime" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tenure_computed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tenure_computed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tenure_computed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "comp_authority_summary" }, "type": { "const": "eq" }, "value": { "properties": { "can_comp_room_night": { "type": "boolean" }, "can_comp_spa": { "type": "boolean" }, "daily_combined_limit": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "last_computed": { "format": "date-time", "type": "string" }, "per_incident_limit": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "active" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sort_preferences" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "board": { "enum": [ "housekeeping_sheet", "housekeeping_rack", "work_orders", "pacing" ], "type": "string" }, "keys": { "items": { "properties": { "direction": { "enum": [ "asc", "desc" ], "type": "string" }, "key": { "enum": [ "priority", "room_number", "floor", "task_type", "status", "due_at", "credits", "arrival_time", "departure_time", "pending_credits", "target_percent", "name" ], "type": "string" }, "values": { "items": { "type": "string" }, "type": "array" } }, "required": [ "key", "direction" ], "type": "object" }, "type": "array" } }, "required": [ "board", "keys" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "push_topics" }, "type": { "const": "eq" }, "value": { "items": { "enum": [ "cleaning_tasks", "faults", "urgent_faults", "postponed_faults", "delegated_faults", "stock" ], "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contracted_weekly_hours" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contracted_weekly_hours" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contracted_weekly_hours" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "employee_id", "given_name", "family_name", "email", "handset_passcode_hash", "identity_subject", "role", "department", "discipline", "pathway_stage_code", "most_recent_hire_date", "tenure_years_at_current_property", "tenure_years_lifetime", "tenure_computed_at", "contracted_weekly_hours" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_member" }, "properties": { "additionalProperties": false, "properties": { "active": { "title": "Active", "type": "boolean" }, "comp_authority_summary": { "description": "Resolved comp authority summary (cache)", "properties": { "can_comp_room_night": { "type": "boolean" }, "can_comp_spa": { "type": "boolean" }, "daily_combined_limit": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "last_computed": { "format": "date-time", "type": "string" }, "per_incident_limit": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "title": "Staff member comp authority summary", "type": "object" }, "contracted_weekly_hours": { "format": "decimal", "title": "The hours a week the staff member is contracted for (more than 0, at most 168) — what the pacing report's percentage_worked is of", "type": "string" }, "department": { "title": "Department", "type": "string" }, "discipline": { "enum": [ "front_office", "food_beverage", "culinary", "bar", "housekeeping", "engineering", "spa", "wellness_clinical", "wellness_coaching", "sales", "revenue", "management", "other" ], "title": "Discipline", "type": "string" }, "email": { "title": "Email", "type": "string" }, "employee_id": { "title": "Employee ID", "type": "string" }, "family_name": { "title": "Family name", "type": "string" }, "given_name": { "title": "Given name", "type": "string" }, "handset_passcode_hash": { "title": "Handset PIN hash (Argon2id, PHC string)", "type": "string" }, "identity_subject": { "title": "Identity-provider subject (SSO)", "type": "string" }, "most_recent_hire_date": { "format": "date", "title": "Most recent hire date", "type": "string" }, "pathway_stage_code": { "title": "Pathway stage code (operator vocabulary)", "type": "string" }, "push_topics": { "items": { "enum": [ "cleaning_tasks", "faults", "urgent_faults", "postponed_faults", "delegated_faults", "stock" ], "type": "string" }, "title": "The push topics the staff member hears; absent = cleaning_tasks and faults (the nudges every handset has had), and the fault topics (urgent, postponed, delegated) only when named", "type": "array" }, "role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "Role", "type": "string" }, "sort_preferences": { "description": "The staff member's own order for a board, one entry per board — wins over the house's pattern in `board_sort`", "items": { "properties": { "board": { "enum": [ "housekeeping_sheet", "housekeeping_rack", "work_orders", "pacing" ], "type": "string" }, "keys": { "items": { "properties": { "direction": { "enum": [ "asc", "desc" ], "type": "string" }, "key": { "enum": [ "priority", "room_number", "floor", "task_type", "status", "due_at", "credits", "arrival_time", "departure_time", "pending_credits", "target_percent", "name" ], "type": "string" }, "values": { "items": { "type": "string" }, "type": "array" } }, "required": [ "key", "direction" ], "type": "object" }, "type": "array" } }, "required": [ "board", "keys" ], "type": "object" }, "title": "Staff member sort preferences", "type": "array" }, "tenure_computed_at": { "format": "date-time", "title": "Tenure refresh timestamp", "type": "string" }, "tenure_years_at_current_property": { "format": "decimal", "title": "Tenure years at current property (projection)", "type": "string" }, "tenure_years_lifetime": { "format": "decimal", "title": "Tenure years lifetime (projection)", "type": "string" } }, "required": [ "role", "active" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.staff_member:read" ] } ], "summary": "Search Staff member", "tags": [ "people" ] } }, "/v1/object-types/hospitality.staff_shift/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne worked (or in-progress) shift. `department` and `management` are stamped at clock-in — a cross-department day is two shifts, and a later promotion does not rewrite history. Hours are computed at clock-out (`actual_end - actual_start` minus unpaid break) and report under the property-local `business_date` of `actual_start`. Immutable post-close except `voided` (mis-punch correction: void + re-record).", "operationId": "get_hospitality_staff_shift", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_shift" }, "properties": { "additionalProperties": false, "properties": { "actual_end": { "format": "date-time", "title": "Actual end", "type": "string" }, "actual_start": { "format": "date-time", "title": "Actual start", "type": "string" }, "business_date": { "format": "date", "title": "Business date", "type": "string" }, "credit_target": { "format": "decimal", "title": "Housekeeping credits the attendant is expected to clean this shift (zero or more)", "type": "string" }, "department": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "it_services", "retail", "other_operated", "minor_operated", "administrative_general", "information_telecom_systems", "sales_marketing", "property_ops_maintenance", "utilities" ], "title": "USALI 12 Schedule 15 department", "type": "string" }, "id": { "title": "Shift id", "type": "string" }, "management": { "title": "Management", "type": "boolean" }, "notes": { "title": "Notes", "type": "string" }, "scheduled_end": { "format": "date-time", "title": "Scheduled end", "type": "string" }, "scheduled_start": { "format": "date-time", "title": "Scheduled start", "type": "string" }, "source": { "enum": [ "timeclock", "payroll_import", "manual" ], "title": "Source", "type": "string" }, "status": { "enum": [ "open", "closed", "voided" ], "title": "Status", "type": "string" }, "unpaid_break_minutes": { "title": "Unpaid break minutes", "type": "integer" }, "worked_hours": { "format": "decimal", "title": "Worked hours", "type": "string" } }, "required": [ "id", "status", "source" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.staff_shift:read" ] } ], "summary": "Read Staff shift", "tags": [ "labour" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.staff_shift/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne worked (or in-progress) shift. `department` and `management` are stamped at clock-in — a cross-department day is two shifts, and a later promotion does not rewrite history. Hours are computed at clock-out (`actual_end - actual_start` minus unpaid break) and report under the property-local `business_date` of `actual_start`. Immutable post-close except `voided` (mis-punch correction: void + re-record).", "operationId": "get_hospitality_staff_shift_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.staff_shift" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.staff_shift:read" ] } ], "summary": "Read Staff shift as of a watermark", "tags": [ "labour" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.staff_shift/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne worked (or in-progress) shift. `department` and `management` are stamped at clock-in — a cross-department day is two shifts, and a later promotion does not rewrite history. Hours are computed at clock-out (`actual_end - actual_start` minus unpaid break) and report under the property-local `business_date` of `actual_start`. Immutable post-close except `voided` (mis-punch correction: void + re-record).", "operationId": "list_links_hospitality_staff_shift", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.staff_shift:read" ] } ], "summary": "List links of Staff shift", "tags": [ "labour" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.labour_entry_for_shift", "hospitality.link.shift_at_property", "hospitality.link.shift_for_staff_member" ] } } ] }, "/v1/object-types/hospitality.staff_shift/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne worked (or in-progress) shift. `department` and `management` are stamped at clock-in — a cross-department day is two shifts, and a later promotion does not rewrite history. Hours are computed at clock-out (`actual_end - actual_start` minus unpaid break) and report under the property-local `business_date` of `actual_start`. Immutable post-close except `voided` (mis-punch correction: void + re-record).", "operationId": "traverse_hospitality_staff_shift", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.labour_entry_for_shift", "hospitality.link.shift_at_property", "hospitality.link.shift_for_staff_member" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.staff_shift:read" ] } ], "summary": "Traverse from Staff shift", "tags": [ "labour" ] } }, "/v1/object-types/hospitality.staff_shift/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne worked (or in-progress) shift. `department` and `management` are stamped at clock-in — a cross-department day is two shifts, and a later promotion does not rewrite history. Hours are computed at clock-out (`actual_end - actual_start` minus unpaid break) and report under the property-local `business_date` of `actual_start`. Immutable post-close except `voided` (mis-punch correction: void + re-record).", "operationId": "search_hospitality_staff_shift", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "open", "closed", "voided" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "department" }, "type": { "const": "eq" }, "value": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "it_services", "retail", "other_operated", "minor_operated", "administrative_general", "information_telecom_systems", "sales_marketing", "property_ops_maintenance", "utilities" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "management" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "scheduled_start" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "scheduled_start" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "scheduled_start" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "scheduled_end" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "scheduled_end" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "scheduled_end" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "actual_start" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "actual_start" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "actual_start" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "actual_end" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "actual_end" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "actual_end" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "worked_hours" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "worked_hours" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "worked_hours" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "unpaid_break_minutes" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "unpaid_break_minutes" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "unpaid_break_minutes" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source" }, "type": { "const": "eq" }, "value": { "enum": [ "timeclock", "payroll_import", "manual" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "credit_target" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "credit_target" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "credit_target" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "status", "department", "scheduled_start", "scheduled_end", "actual_start", "actual_end", "worked_hours", "unpaid_break_minutes", "business_date", "source", "notes", "credit_target" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.staff_shift" }, "properties": { "additionalProperties": false, "properties": { "actual_end": { "format": "date-time", "title": "Actual end", "type": "string" }, "actual_start": { "format": "date-time", "title": "Actual start", "type": "string" }, "business_date": { "format": "date", "title": "Business date", "type": "string" }, "credit_target": { "format": "decimal", "title": "Housekeeping credits the attendant is expected to clean this shift (zero or more)", "type": "string" }, "department": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "it_services", "retail", "other_operated", "minor_operated", "administrative_general", "information_telecom_systems", "sales_marketing", "property_ops_maintenance", "utilities" ], "title": "USALI 12 Schedule 15 department", "type": "string" }, "id": { "title": "Shift id", "type": "string" }, "management": { "title": "Management", "type": "boolean" }, "notes": { "title": "Notes", "type": "string" }, "scheduled_end": { "format": "date-time", "title": "Scheduled end", "type": "string" }, "scheduled_start": { "format": "date-time", "title": "Scheduled start", "type": "string" }, "source": { "enum": [ "timeclock", "payroll_import", "manual" ], "title": "Source", "type": "string" }, "status": { "enum": [ "open", "closed", "voided" ], "title": "Status", "type": "string" }, "unpaid_break_minutes": { "title": "Unpaid break minutes", "type": "integer" }, "worked_hours": { "format": "decimal", "title": "Worked hours", "type": "string" } }, "required": [ "id", "status", "source" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.staff_shift:read" ] } ], "summary": "Search Staff shift", "tags": [ "labour" ] } }, "/v1/object-types/hospitality.stay/objects/{id}": { "get": { "description": "Read an existing instance.\n\nThe execution of a reservation: the actual arrival, room assignment, in-house period, and departure. Charges and payments hang off the stay's folio.", "operationId": "get_hospitality_stay", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" }, "properties": { "additionalProperties": false, "properties": { "arrival_actual": { "format": "date-time", "title": "Actual arrival", "type": "string" }, "credit_limit": { "description": "The most the desk lets the stay's bill reach, the room still to come included — OPERA's credit limit set for the guest's payment method. A till's posting is held to the greater of this and what the stay's live card holds hold, less the bills' balance and the room still due; over it the posting is refused (`no_credit`) unless a manager overrides. With neither a limit nor a hold, no credit rule applies. Set by the desk with set_posting_rules.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Stay credit limit", "type": "object" }, "departure_actual": { "format": "date-time", "title": "Actual departure", "type": "string" }, "green_stay": { "title": "The guest declined the day's clean for sustainability — while set, generate_housekeeping_tasks mints no stayover clean for the room (a shared room only when every guest in it declined)", "type": "boolean" }, "green_stay_set_at": { "format": "date-time", "title": "When the green stay was set (present while green_stay is true)", "type": "string" }, "hold_top_up_attempt": { "title": "The card rail's open top-up attempt — the id its processor keys are derived from; cleared when the attempt is recorded", "type": "string" }, "hold_top_up_attempt_amount": { "description": "What the open top-up attempt holds (or, for a credit-limit charge, holds afresh)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Stay hold top up attempt amount", "type": "object" }, "hold_top_up_attempt_capture": { "description": "What an open credit-limit charge takes from the holds", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Stay hold top up attempt capture", "type": "object" }, "hold_top_up_attempt_holds": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.payment" }, "title": "The holds the open attempt acts on, largest first: those a credit-limit charge takes, or the hold whose card a top-up goes on", "type": "array" }, "hold_top_up_attempt_kind": { "enum": [ "top_up", "overage_charge" ], "title": "top_up (a second hold or an increment) or overage_charge", "type": "string" }, "hold_top_up_attempt_opened_at": { "format": "date-time", "title": "When the open top-up attempt was written down; past 23 hours it is abandoned and a new one opened", "type": "string" }, "hold_top_up_last_at": { "format": "date-time", "title": "When the last top-up was placed", "type": "string" }, "hold_top_up_refusal": { "enum": [ "card_declined", "insufficient_funds", "authentication_required", "no_consent", "no_card", "max_reached", "other_currency", "processor_refused", "attempt_abandoned" ], "title": "Why the last top-up took nothing, until one takes something", "type": "string" }, "hold_top_up_refusal_balance": { "description": "The bill's balance when that refusal was recorded", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Stay hold top up refusal balance", "type": "object" }, "hold_top_up_refusal_detail": { "title": "The processor's words for that refusal", "type": "string" }, "hold_top_up_refused_at": { "format": "date-time", "title": "When that refusal was recorded", "type": "string" }, "hold_top_ups": { "title": "How many top-ups the card rail has placed for this stay", "type": "integer" }, "id": { "title": "Stay id", "type": "string" }, "no_post": { "description": "OPERA's NOPOST: while true, a till's room charge or charge-to-key to this stay is refused (`no_post`) unless a manager's override is recorded on the payment. Set by the desk with set_posting_rules; unset reads as false.", "title": "No outlet may post to the stay's bill", "type": "boolean" }, "post_stay_collection_amount": { "description": "What the open collection attempt asks for", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Stay post stay collection amount", "type": "object" }, "post_stay_collection_attempt": { "title": "The card rail's open collection attempt — the id its processor keys are derived from; cleared when the attempt is recorded", "type": "string" }, "post_stay_refusal": { "enum": [ "window_closed", "post_stay_charging_off", "authentication_required", "declined", "no_card" ], "title": "Why the last post-stay collection took nothing, until one takes something", "type": "string" }, "post_stay_refusal_balance": { "description": "The bill's balance when that refusal was recorded", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Stay post stay refusal balance", "type": "object" }, "post_stay_window": { "enum": [ "open", "closed" ], "title": "open while charges found after departure may still post; closed after", "type": "string" }, "post_stay_window_closed_at": { "format": "date-time", "title": "When the card rail closed the post-stay window", "type": "string" }, "post_stay_window_until": { "format": "date-time", "title": "When the post-stay window closes — the house's midnight after the window's last business day", "type": "string" }, "room_assignment_status": { "enum": [ "pending", "assigned", "occupied", "released" ], "title": "Room assignment status", "type": "string" }, "status": { "enum": [ "not_arrived", "in_house", "checked_out", "no_show", "cancelled" ], "title": "Stay state", "type": "string" } }, "required": [ "id", "status", "room_assignment_status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stay:read" ] } ], "summary": "Read Stay", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.stay/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nThe execution of a reservation: the actual arrival, room assignment, in-house period, and departure. Charges and payments hang off the stay's folio.", "operationId": "get_hospitality_stay_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.stay" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stay:read" ] } ], "summary": "Read Stay as of a watermark", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.stay/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nThe execution of a reservation: the actual arrival, room assignment, in-house period, and departure. Charges and payments hang off the stay's folio.", "operationId": "list_links_hospitality_stay", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stay:read" ] } ], "summary": "List links of Stay", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.access_credential_for_stay", "hospitality.link.check_for_stay", "hospitality.link.guest_feedback_for_stay", "hospitality.link.housekeeping_task_requested_by_stay", "hospitality.link.rail_instruction_for_stay", "hospitality.link.registration_card_for_stay", "hospitality.link.reservation_has_stay", "hospitality.link.stay_for_reservation_room", "hospitality.link.stay_has_folio", "hospitality.link.stay_in_room", "hospitality.link.work_order_reported_by_stay" ] } } ] }, "/v1/object-types/hospitality.stay/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nThe execution of a reservation: the actual arrival, room assignment, in-house period, and departure. Charges and payments hang off the stay's folio.", "operationId": "traverse_hospitality_stay", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.access_credential_for_stay", "hospitality.link.check_for_stay", "hospitality.link.guest_feedback_for_stay", "hospitality.link.housekeeping_task_requested_by_stay", "hospitality.link.rail_instruction_for_stay", "hospitality.link.registration_card_for_stay", "hospitality.link.reservation_has_stay", "hospitality.link.stay_for_reservation_room", "hospitality.link.stay_has_folio", "hospitality.link.stay_in_room", "hospitality.link.work_order_reported_by_stay" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stay:read" ] } ], "summary": "Traverse from Stay", "tags": [ "booking" ] } }, "/v1/object-types/hospitality.stay/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nThe execution of a reservation: the actual arrival, room assignment, in-house period, and departure. Charges and payments hang off the stay's folio.", "operationId": "search_hospitality_stay", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "not_arrived", "in_house", "checked_out", "no_show", "cancelled" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "arrival_actual" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "arrival_actual" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "arrival_actual" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "departure_actual" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "departure_actual" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "departure_actual" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "room_assignment_status" }, "type": { "const": "eq" }, "value": { "enum": [ "pending", "assigned", "occupied", "released" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "green_stay" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "green_stay_set_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "green_stay_set_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "green_stay_set_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "post_stay_window" }, "type": { "const": "eq" }, "value": { "enum": [ "open", "closed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "post_stay_window_until" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "post_stay_window_until" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "post_stay_window_until" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "post_stay_window_closed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "post_stay_window_closed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "post_stay_window_closed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "post_stay_collection_attempt" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "post_stay_collection_attempt" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "post_stay_collection_attempt" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "post_stay_collection_attempt" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "post_stay_collection_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "post_stay_refusal" }, "type": { "const": "eq" }, "value": { "enum": [ "window_closed", "post_stay_charging_off", "authentication_required", "declined", "no_card" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "post_stay_refusal_balance" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_attempt" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_attempt" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_attempt" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_attempt" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_attempt_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_attempt_capture" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_attempt_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "top_up", "overage_charge" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_ups" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_ups" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_ups" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_last_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_last_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_last_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_refusal" }, "type": { "const": "eq" }, "value": { "enum": [ "card_declined", "insufficient_funds", "authentication_required", "no_consent", "no_card", "max_reached", "other_currency", "processor_refused", "attempt_abandoned" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_refusal_detail" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_refusal_detail" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_refusal_balance" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_refused_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_refused_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_refused_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_attempt_opened_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_attempt_opened_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_attempt_opened_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "hold_top_up_attempt_holds" }, "type": { "const": "eq" }, "value": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.payment" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "no_post" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "credit_limit" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "status", "arrival_actual", "departure_actual", "room_assignment_status", "green_stay_set_at", "post_stay_window", "post_stay_window_until", "post_stay_window_closed_at", "post_stay_collection_attempt", "post_stay_refusal", "hold_top_up_attempt", "hold_top_up_attempt_kind", "hold_top_ups", "hold_top_up_last_at", "hold_top_up_refusal", "hold_top_up_refusal_detail", "hold_top_up_refused_at", "hold_top_up_attempt_opened_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay" }, "properties": { "additionalProperties": false, "properties": { "arrival_actual": { "format": "date-time", "title": "Actual arrival", "type": "string" }, "credit_limit": { "description": "The most the desk lets the stay's bill reach, the room still to come included — OPERA's credit limit set for the guest's payment method. A till's posting is held to the greater of this and what the stay's live card holds hold, less the bills' balance and the room still due; over it the posting is refused (`no_credit`) unless a manager overrides. With neither a limit nor a hold, no credit rule applies. Set by the desk with set_posting_rules.", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Stay credit limit", "type": "object" }, "departure_actual": { "format": "date-time", "title": "Actual departure", "type": "string" }, "green_stay": { "title": "The guest declined the day's clean for sustainability — while set, generate_housekeeping_tasks mints no stayover clean for the room (a shared room only when every guest in it declined)", "type": "boolean" }, "green_stay_set_at": { "format": "date-time", "title": "When the green stay was set (present while green_stay is true)", "type": "string" }, "hold_top_up_attempt": { "title": "The card rail's open top-up attempt — the id its processor keys are derived from; cleared when the attempt is recorded", "type": "string" }, "hold_top_up_attempt_amount": { "description": "What the open top-up attempt holds (or, for a credit-limit charge, holds afresh)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Stay hold top up attempt amount", "type": "object" }, "hold_top_up_attempt_capture": { "description": "What an open credit-limit charge takes from the holds", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Stay hold top up attempt capture", "type": "object" }, "hold_top_up_attempt_holds": { "items": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.payment" }, "title": "The holds the open attempt acts on, largest first: those a credit-limit charge takes, or the hold whose card a top-up goes on", "type": "array" }, "hold_top_up_attempt_kind": { "enum": [ "top_up", "overage_charge" ], "title": "top_up (a second hold or an increment) or overage_charge", "type": "string" }, "hold_top_up_attempt_opened_at": { "format": "date-time", "title": "When the open top-up attempt was written down; past 23 hours it is abandoned and a new one opened", "type": "string" }, "hold_top_up_last_at": { "format": "date-time", "title": "When the last top-up was placed", "type": "string" }, "hold_top_up_refusal": { "enum": [ "card_declined", "insufficient_funds", "authentication_required", "no_consent", "no_card", "max_reached", "other_currency", "processor_refused", "attempt_abandoned" ], "title": "Why the last top-up took nothing, until one takes something", "type": "string" }, "hold_top_up_refusal_balance": { "description": "The bill's balance when that refusal was recorded", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Stay hold top up refusal balance", "type": "object" }, "hold_top_up_refusal_detail": { "title": "The processor's words for that refusal", "type": "string" }, "hold_top_up_refused_at": { "format": "date-time", "title": "When that refusal was recorded", "type": "string" }, "hold_top_ups": { "title": "How many top-ups the card rail has placed for this stay", "type": "integer" }, "id": { "title": "Stay id", "type": "string" }, "no_post": { "description": "OPERA's NOPOST: while true, a till's room charge or charge-to-key to this stay is refused (`no_post`) unless a manager's override is recorded on the payment. Set by the desk with set_posting_rules; unset reads as false.", "title": "No outlet may post to the stay's bill", "type": "boolean" }, "post_stay_collection_amount": { "description": "What the open collection attempt asks for", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Stay post stay collection amount", "type": "object" }, "post_stay_collection_attempt": { "title": "The card rail's open collection attempt — the id its processor keys are derived from; cleared when the attempt is recorded", "type": "string" }, "post_stay_refusal": { "enum": [ "window_closed", "post_stay_charging_off", "authentication_required", "declined", "no_card" ], "title": "Why the last post-stay collection took nothing, until one takes something", "type": "string" }, "post_stay_refusal_balance": { "description": "The bill's balance when that refusal was recorded", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Stay post stay refusal balance", "type": "object" }, "post_stay_window": { "enum": [ "open", "closed" ], "title": "open while charges found after departure may still post; closed after", "type": "string" }, "post_stay_window_closed_at": { "format": "date-time", "title": "When the card rail closed the post-stay window", "type": "string" }, "post_stay_window_until": { "format": "date-time", "title": "When the post-stay window closes — the house's midnight after the window's last business day", "type": "string" }, "room_assignment_status": { "enum": [ "pending", "assigned", "occupied", "released" ], "title": "Room assignment status", "type": "string" }, "status": { "enum": [ "not_arrived", "in_house", "checked_out", "no_show", "cancelled" ], "title": "Stay state", "type": "string" } }, "required": [ "id", "status", "room_assignment_status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stay:read" ] } ], "summary": "Search Stay", "tags": [ "booking" ] } }, "/v1/object-types/hospitality.stay_offer/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne room type on one rate plan the house quoted a shopper and kept: the stay (`arrival_date`, `departure_date`), the party (`adults`), the published arrival-night rate (`quoted_rate`) and stay total the admission gate priced, when it was quoted (`offered_at`, business time), the channel the shopper came through, the shopping session the house issued (`session_id`) and the visitor key it issued for the browser (`visitor_id`). A search stays the read `quote_stay` is; the offer is the room and rate a shopper opened. A reservation made in the session links to its first offer (`reservation_booked_in_session`), and a session that booked nothing is a regret, derived — `regret_record` — never recorded. Holds no inventory.", "operationId": "get_hospitality_stay_offer", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay_offer" }, "properties": { "additionalProperties": false, "properties": { "adults": { "title": "Adults — the occupancy the grid priced", "type": "integer" }, "arrival_date": { "format": "date", "title": "Arrival night", "type": "string" }, "departure_date": { "format": "date", "title": "Departure date", "type": "string" }, "id": { "title": "Offer id", "type": "string" }, "offered_at": { "format": "date-time", "title": "When the house quoted it (business time; defaults to now)", "type": "string" }, "quoted_rate": { "description": "Rate quoted", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Stay offer quoted rate", "type": "object" }, "session_id": { "title": "Shopping session", "type": "string" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "Channel the shopper came through", "type": "string" }, "total": { "description": "Stay total quoted", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Stay offer total", "type": "object" }, "visitor_id": { "title": "Visitor key the house issued", "type": "string" } }, "required": [ "id", "offered_at", "arrival_date", "departure_date", "adults", "quoted_rate", "total", "source", "session_id" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stay_offer:read" ] } ], "summary": "Read Stay offer", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.stay_offer/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne room type on one rate plan the house quoted a shopper and kept: the stay (`arrival_date`, `departure_date`), the party (`adults`), the published arrival-night rate (`quoted_rate`) and stay total the admission gate priced, when it was quoted (`offered_at`, business time), the channel the shopper came through, the shopping session the house issued (`session_id`) and the visitor key it issued for the browser (`visitor_id`). A search stays the read `quote_stay` is; the offer is the room and rate a shopper opened. A reservation made in the session links to its first offer (`reservation_booked_in_session`), and a session that booked nothing is a regret, derived — `regret_record` — never recorded. Holds no inventory.", "operationId": "get_hospitality_stay_offer_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.stay_offer" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stay_offer:read" ] } ], "summary": "Read Stay offer as of a watermark", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.stay_offer/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne room type on one rate plan the house quoted a shopper and kept: the stay (`arrival_date`, `departure_date`), the party (`adults`), the published arrival-night rate (`quoted_rate`) and stay total the admission gate priced, when it was quoted (`offered_at`, business time), the channel the shopper came through, the shopping session the house issued (`session_id`) and the visitor key it issued for the browser (`visitor_id`). A search stays the read `quote_stay` is; the offer is the room and rate a shopper opened. A reservation made in the session links to its first offer (`reservation_booked_in_session`), and a session that booked nothing is a regret, derived — `regret_record` — never recorded. Holds no inventory.", "operationId": "list_links_hospitality_stay_offer", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stay_offer:read" ] } ], "summary": "List links of Stay offer", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.reservation_booked_in_session", "hospitality.link.stay_offer_for_property", "hospitality.link.stay_offer_for_rate_plan", "hospitality.link.stay_offer_for_room_type" ] } } ] }, "/v1/object-types/hospitality.stay_offer/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne room type on one rate plan the house quoted a shopper and kept: the stay (`arrival_date`, `departure_date`), the party (`adults`), the published arrival-night rate (`quoted_rate`) and stay total the admission gate priced, when it was quoted (`offered_at`, business time), the channel the shopper came through, the shopping session the house issued (`session_id`) and the visitor key it issued for the browser (`visitor_id`). A search stays the read `quote_stay` is; the offer is the room and rate a shopper opened. A reservation made in the session links to its first offer (`reservation_booked_in_session`), and a session that booked nothing is a regret, derived — `regret_record` — never recorded. Holds no inventory.", "operationId": "traverse_hospitality_stay_offer", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.reservation_booked_in_session", "hospitality.link.stay_offer_for_property", "hospitality.link.stay_offer_for_rate_plan", "hospitality.link.stay_offer_for_room_type" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stay_offer:read" ] } ], "summary": "Traverse from Stay offer", "tags": [ "booking" ] } }, "/v1/object-types/hospitality.stay_offer/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne room type on one rate plan the house quoted a shopper and kept: the stay (`arrival_date`, `departure_date`), the party (`adults`), the published arrival-night rate (`quoted_rate`) and stay total the admission gate priced, when it was quoted (`offered_at`, business time), the channel the shopper came through, the shopping session the house issued (`session_id`) and the visitor key it issued for the browser (`visitor_id`). A search stays the read `quote_stay` is; the offer is the room and rate a shopper opened. A reservation made in the session links to its first offer (`reservation_booked_in_session`), and a session that booked nothing is a regret, derived — `regret_record` — never recorded. Holds no inventory.", "operationId": "search_hospitality_stay_offer", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "offered_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "offered_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "offered_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "arrival_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "arrival_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "arrival_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "departure_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "departure_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "departure_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "adults" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "adults" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "adults" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quoted_rate" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "total" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source" }, "type": { "const": "eq" }, "value": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "session_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "session_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "session_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "session_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "visitor_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "visitor_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "visitor_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "visitor_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "offered_at", "arrival_date", "departure_date", "adults", "source", "session_id", "visitor_id" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stay_offer" }, "properties": { "additionalProperties": false, "properties": { "adults": { "title": "Adults — the occupancy the grid priced", "type": "integer" }, "arrival_date": { "format": "date", "title": "Arrival night", "type": "string" }, "departure_date": { "format": "date", "title": "Departure date", "type": "string" }, "id": { "title": "Offer id", "type": "string" }, "offered_at": { "format": "date-time", "title": "When the house quoted it (business time; defaults to now)", "type": "string" }, "quoted_rate": { "description": "Rate quoted", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Stay offer quoted rate", "type": "object" }, "session_id": { "title": "Shopping session", "type": "string" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "Channel the shopper came through", "type": "string" }, "total": { "description": "Stay total quoted", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Stay offer total", "type": "object" }, "visitor_id": { "title": "Visitor key the house issued", "type": "string" } }, "required": [ "id", "offered_at", "arrival_date", "departure_date", "adults", "quoted_rate", "total", "source", "session_id" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stay_offer:read" ] } ], "summary": "Search Stay offer", "tags": [ "booking" ] } }, "/v1/object-types/hospitality.stock_level/objects/{id}": { "get": { "description": "Read an existing instance.\n\nHow much of one material one store holds — one row per material × store, linked `stock_level_for_material` and `stock_level_in_store` (the ids ride on the row too, so a store's board filters without a walk). `on_hand` is a cache with one writer: every movement verb records its `stock_movement` and moves this figure in the same transaction, under the level's lock; the movements are the truth and `recount_stock_level` folds them to check it. Never below zero unless the store allows it. Carries the `reorder_point` (OPERA's par) and when it was last counted. Minted by the first movement (or reorder point) for the pair.", "operationId": "get_hospitality_stock_level", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_level" }, "properties": { "additionalProperties": false, "properties": { "id": { "title": "Stock level id", "type": "string" }, "last_counted_at": { "format": "date-time", "title": "When it was last physically counted", "type": "string" }, "last_movement_at": { "format": "date-time", "title": "When its last movement was recorded", "type": "string" }, "material_id": { "title": "The material counted (its `stock_level_for_material` edge, on the row)", "type": "string" }, "on_hand": { "format": "decimal", "title": "How much the store holds, in the material's unit — the sum of the level's movements", "type": "string" }, "reorder_point": { "format": "decimal", "title": "At or below this, the store's stock of the material is reordered (OPERA's par)", "type": "string" }, "store_id": { "title": "The store it is kept in (its `stock_level_in_store` edge, on the row)", "type": "string" } }, "required": [ "id", "material_id", "store_id", "on_hand" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stock_level:read" ] } ], "summary": "Read Stock level", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.stock_level/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nHow much of one material one store holds — one row per material × store, linked `stock_level_for_material` and `stock_level_in_store` (the ids ride on the row too, so a store's board filters without a walk). `on_hand` is a cache with one writer: every movement verb records its `stock_movement` and moves this figure in the same transaction, under the level's lock; the movements are the truth and `recount_stock_level` folds them to check it. Never below zero unless the store allows it. Carries the `reorder_point` (OPERA's par) and when it was last counted. Minted by the first movement (or reorder point) for the pair.", "operationId": "get_hospitality_stock_level_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.stock_level" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stock_level:read" ] } ], "summary": "Read Stock level as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.stock_level/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nHow much of one material one store holds — one row per material × store, linked `stock_level_for_material` and `stock_level_in_store` (the ids ride on the row too, so a store's board filters without a walk). `on_hand` is a cache with one writer: every movement verb records its `stock_movement` and moves this figure in the same transaction, under the level's lock; the movements are the truth and `recount_stock_level` folds them to check it. Never below zero unless the store allows it. Carries the `reorder_point` (OPERA's par) and when it was last counted. Minted by the first movement (or reorder point) for the pair.", "operationId": "list_links_hospitality_stock_level", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stock_level:read" ] } ], "summary": "List links of Stock level", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.stock_level_for_material", "hospitality.link.stock_level_in_store", "hospitality.link.stock_movement_for_level" ] } } ] }, "/v1/object-types/hospitality.stock_level/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nHow much of one material one store holds — one row per material × store, linked `stock_level_for_material` and `stock_level_in_store` (the ids ride on the row too, so a store's board filters without a walk). `on_hand` is a cache with one writer: every movement verb records its `stock_movement` and moves this figure in the same transaction, under the level's lock; the movements are the truth and `recount_stock_level` folds them to check it. Never below zero unless the store allows it. Carries the `reorder_point` (OPERA's par) and when it was last counted. Minted by the first movement (or reorder point) for the pair.", "operationId": "traverse_hospitality_stock_level", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.stock_level_for_material", "hospitality.link.stock_level_in_store", "hospitality.link.stock_movement_for_level" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stock_level:read" ] } ], "summary": "Traverse from Stock level", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.stock_level/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nHow much of one material one store holds — one row per material × store, linked `stock_level_for_material` and `stock_level_in_store` (the ids ride on the row too, so a store's board filters without a walk). `on_hand` is a cache with one writer: every movement verb records its `stock_movement` and moves this figure in the same transaction, under the level's lock; the movements are the truth and `recount_stock_level` folds them to check it. Never below zero unless the store allows it. Carries the `reorder_point` (OPERA's par) and when it was last counted. Minted by the first movement (or reorder point) for the pair.", "operationId": "search_hospitality_stock_level", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "material_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "material_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "material_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "material_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "store_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "store_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "store_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "store_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "on_hand" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "on_hand" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "on_hand" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reorder_point" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reorder_point" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reorder_point" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_counted_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_counted_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_counted_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_movement_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_movement_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_movement_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "material_id", "store_id", "on_hand", "reorder_point", "last_counted_at", "last_movement_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_level" }, "properties": { "additionalProperties": false, "properties": { "id": { "title": "Stock level id", "type": "string" }, "last_counted_at": { "format": "date-time", "title": "When it was last physically counted", "type": "string" }, "last_movement_at": { "format": "date-time", "title": "When its last movement was recorded", "type": "string" }, "material_id": { "title": "The material counted (its `stock_level_for_material` edge, on the row)", "type": "string" }, "on_hand": { "format": "decimal", "title": "How much the store holds, in the material's unit — the sum of the level's movements", "type": "string" }, "reorder_point": { "format": "decimal", "title": "At or below this, the store's stock of the material is reordered (OPERA's par)", "type": "string" }, "store_id": { "title": "The store it is kept in (its `stock_level_in_store` edge, on the row)", "type": "string" } }, "required": [ "id", "material_id", "store_id", "on_hand" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stock_level:read" ] } ], "summary": "Search Stock level", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.stock_movement/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne movement of stock into or out of a store, on its level (`stock_movement_for_level`): a `receipt`, an `issue`, a `consumption` (on a fault — `stock_movement_for_work_order` — or a minibar task — `stock_movement_for_housekeeping_task`), an `adjustment` with its reason, a `count` (the level set to what was counted; the movement carries the difference), or one leg of a `transfer` (the receiving leg names the issuing one, `stock_movement_transfer_from`). `quantity` is signed, in the material's unit; `on_hand_before` and `on_hand_after` are the level either side of it, so a store's stock card reads off its movements. Each kind is pinned to its sign and its references by validator. `recorded_by` names the principal; a staff member who recorded it is linked (`stock_movement_recorded_by`). Never edited: a correction is another movement.", "operationId": "get_hospitality_stock_movement", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_movement" }, "properties": { "additionalProperties": false, "properties": { "charged": { "description": "What the guest was charged for it (a minibar consumption)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Stock movement charged", "type": "object" }, "counted": { "format": "decimal", "title": "What a count found (a count movement only; equals on_hand_after)", "type": "string" }, "id": { "title": "Stock movement id", "type": "string" }, "kind": { "enum": [ "receipt", "issue", "consumption", "adjustment", "count", "transfer" ], "title": "receipt, issue, consumption, adjustment, count, transfer", "type": "string" }, "on_hand_after": { "format": "decimal", "title": "The level after it — on_hand_before + quantity", "type": "string" }, "on_hand_before": { "format": "decimal", "title": "The level before this movement", "type": "string" }, "quantity": { "format": "decimal", "title": "How much moved, signed (in positive, out negative), in the material's unit", "type": "string" }, "reason": { "title": "Why — required for an adjustment (breakage, expiry, theft)", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When it was recorded — the handset's own time when it queued offline", "type": "string" }, "recorded_by": { "title": "The principal that recorded it (`user:…`, `agent:…`, `service:…`, `system`)", "type": "string" }, "reference": { "title": "An outside reference — the supplier's delivery note, an invoice number", "type": "string" }, "uncharged": { "description": "What it would have charged — a minibar consumption recorded with nobody in house, the desk's late charge (never beside charged)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Stock movement uncharged", "type": "object" } }, "required": [ "id", "kind", "quantity", "on_hand_before", "on_hand_after", "recorded_at", "recorded_by" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stock_movement:read" ] } ], "summary": "Read Stock movement", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.stock_movement/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne movement of stock into or out of a store, on its level (`stock_movement_for_level`): a `receipt`, an `issue`, a `consumption` (on a fault — `stock_movement_for_work_order` — or a minibar task — `stock_movement_for_housekeeping_task`), an `adjustment` with its reason, a `count` (the level set to what was counted; the movement carries the difference), or one leg of a `transfer` (the receiving leg names the issuing one, `stock_movement_transfer_from`). `quantity` is signed, in the material's unit; `on_hand_before` and `on_hand_after` are the level either side of it, so a store's stock card reads off its movements. Each kind is pinned to its sign and its references by validator. `recorded_by` names the principal; a staff member who recorded it is linked (`stock_movement_recorded_by`). Never edited: a correction is another movement.", "operationId": "get_hospitality_stock_movement_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.stock_movement" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stock_movement:read" ] } ], "summary": "Read Stock movement as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.stock_movement/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne movement of stock into or out of a store, on its level (`stock_movement_for_level`): a `receipt`, an `issue`, a `consumption` (on a fault — `stock_movement_for_work_order` — or a minibar task — `stock_movement_for_housekeeping_task`), an `adjustment` with its reason, a `count` (the level set to what was counted; the movement carries the difference), or one leg of a `transfer` (the receiving leg names the issuing one, `stock_movement_transfer_from`). `quantity` is signed, in the material's unit; `on_hand_before` and `on_hand_after` are the level either side of it, so a store's stock card reads off its movements. Each kind is pinned to its sign and its references by validator. `recorded_by` names the principal; a staff member who recorded it is linked (`stock_movement_recorded_by`). Never edited: a correction is another movement.", "operationId": "list_links_hospitality_stock_movement", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stock_movement:read" ] } ], "summary": "List links of Stock movement", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.charge_for_stock_movement", "hospitality.link.stock_movement_for_housekeeping_task", "hospitality.link.stock_movement_for_level", "hospitality.link.stock_movement_for_room", "hospitality.link.stock_movement_for_work_order", "hospitality.link.stock_movement_recorded_by", "hospitality.link.stock_movement_transfer_from" ] } } ] }, "/v1/object-types/hospitality.stock_movement/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne movement of stock into or out of a store, on its level (`stock_movement_for_level`): a `receipt`, an `issue`, a `consumption` (on a fault — `stock_movement_for_work_order` — or a minibar task — `stock_movement_for_housekeeping_task`), an `adjustment` with its reason, a `count` (the level set to what was counted; the movement carries the difference), or one leg of a `transfer` (the receiving leg names the issuing one, `stock_movement_transfer_from`). `quantity` is signed, in the material's unit; `on_hand_before` and `on_hand_after` are the level either side of it, so a store's stock card reads off its movements. Each kind is pinned to its sign and its references by validator. `recorded_by` names the principal; a staff member who recorded it is linked (`stock_movement_recorded_by`). Never edited: a correction is another movement.", "operationId": "traverse_hospitality_stock_movement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.charge_for_stock_movement", "hospitality.link.stock_movement_for_housekeeping_task", "hospitality.link.stock_movement_for_level", "hospitality.link.stock_movement_for_room", "hospitality.link.stock_movement_for_work_order", "hospitality.link.stock_movement_recorded_by", "hospitality.link.stock_movement_transfer_from" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stock_movement:read" ] } ], "summary": "Traverse from Stock movement", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.stock_movement/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne movement of stock into or out of a store, on its level (`stock_movement_for_level`): a `receipt`, an `issue`, a `consumption` (on a fault — `stock_movement_for_work_order` — or a minibar task — `stock_movement_for_housekeeping_task`), an `adjustment` with its reason, a `count` (the level set to what was counted; the movement carries the difference), or one leg of a `transfer` (the receiving leg names the issuing one, `stock_movement_transfer_from`). `quantity` is signed, in the material's unit; `on_hand_before` and `on_hand_after` are the level either side of it, so a store's stock card reads off its movements. Each kind is pinned to its sign and its references by validator. `recorded_by` names the principal; a staff member who recorded it is linked (`stock_movement_recorded_by`). Never edited: a correction is another movement.", "operationId": "search_hospitality_stock_movement", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "receipt", "issue", "consumption", "adjustment", "count", "transfer" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quantity" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quantity" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quantity" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "on_hand_before" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "on_hand_before" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "on_hand_before" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "on_hand_after" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "on_hand_after" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "on_hand_after" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "counted" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "counted" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "counted" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "charged" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "uncharged" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "kind", "quantity", "on_hand_before", "on_hand_after", "counted", "reason", "reference", "recorded_at", "recorded_by" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_movement" }, "properties": { "additionalProperties": false, "properties": { "charged": { "description": "What the guest was charged for it (a minibar consumption)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Stock movement charged", "type": "object" }, "counted": { "format": "decimal", "title": "What a count found (a count movement only; equals on_hand_after)", "type": "string" }, "id": { "title": "Stock movement id", "type": "string" }, "kind": { "enum": [ "receipt", "issue", "consumption", "adjustment", "count", "transfer" ], "title": "receipt, issue, consumption, adjustment, count, transfer", "type": "string" }, "on_hand_after": { "format": "decimal", "title": "The level after it — on_hand_before + quantity", "type": "string" }, "on_hand_before": { "format": "decimal", "title": "The level before this movement", "type": "string" }, "quantity": { "format": "decimal", "title": "How much moved, signed (in positive, out negative), in the material's unit", "type": "string" }, "reason": { "title": "Why — required for an adjustment (breakage, expiry, theft)", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When it was recorded — the handset's own time when it queued offline", "type": "string" }, "recorded_by": { "title": "The principal that recorded it (`user:…`, `agent:…`, `service:…`, `system`)", "type": "string" }, "reference": { "title": "An outside reference — the supplier's delivery note, an invoice number", "type": "string" }, "uncharged": { "description": "What it would have charged — a minibar consumption recorded with nobody in house, the desk's late charge (never beside charged)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Stock movement uncharged", "type": "object" } }, "required": [ "id", "kind", "quantity", "on_hand_before", "on_hand_after", "recorded_at", "recorded_by" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stock_movement:read" ] } ], "summary": "Search Stock movement", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.stock_store/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA place a house keeps stock: the stores room, a floor cupboard, the minibar cart, one room's minibar (linked `stock_store_in_room`), the laundry, the workshop. Keyed by `code` within the house; `define_stock_store` with a code the house holds re-states it in place. `is_default` marks the house's store of its kind that work draws from when it names none — a minibar task in a room with no minibar of its own draws from the default minibar cart, a laundry task from the default laundry, a fault's material line from the default workshop (one default per kind). A store's stock may go below zero only when it says so (`allow_negative`): a house that does not count its minibar carts lets them run negative rather than refuse a guest's charge.", "operationId": "get_hospitality_stock_store", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_store" }, "properties": { "additionalProperties": false, "properties": { "allow_negative": { "title": "Whether its stock may go below zero (an uncounted store)", "type": "boolean" }, "code": { "title": "The house's code for the store — unique within the house", "type": "string" }, "defined_at": { "format": "date-time", "title": "When it was first defined", "type": "string" }, "is_default": { "title": "The house's store of its kind that work draws from when it names none", "type": "boolean" }, "kind": { "enum": [ "main_store", "floor_store", "minibar_cart", "room_minibar", "laundry", "workshop" ], "title": "main_store, floor_store, minibar_cart, room_minibar, laundry, workshop", "type": "string" }, "name": { "title": "The store in words (\"Stores\", \"Floor 3 linen\", \"Minibar 101\")", "type": "string" } }, "required": [ "code", "name", "kind", "allow_negative", "defined_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stock_store:read" ] } ], "summary": "Read Stock store", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.stock_store/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA place a house keeps stock: the stores room, a floor cupboard, the minibar cart, one room's minibar (linked `stock_store_in_room`), the laundry, the workshop. Keyed by `code` within the house; `define_stock_store` with a code the house holds re-states it in place. `is_default` marks the house's store of its kind that work draws from when it names none — a minibar task in a room with no minibar of its own draws from the default minibar cart, a laundry task from the default laundry, a fault's material line from the default workshop (one default per kind). A store's stock may go below zero only when it says so (`allow_negative`): a house that does not count its minibar carts lets them run negative rather than refuse a guest's charge.", "operationId": "get_hospitality_stock_store_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.stock_store" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stock_store:read" ] } ], "summary": "Read Stock store as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.stock_store/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA place a house keeps stock: the stores room, a floor cupboard, the minibar cart, one room's minibar (linked `stock_store_in_room`), the laundry, the workshop. Keyed by `code` within the house; `define_stock_store` with a code the house holds re-states it in place. `is_default` marks the house's store of its kind that work draws from when it names none — a minibar task in a room with no minibar of its own draws from the default minibar cart, a laundry task from the default laundry, a fault's material line from the default workshop (one default per kind). A store's stock may go below zero only when it says so (`allow_negative`): a house that does not count its minibar carts lets them run negative rather than refuse a guest's charge.", "operationId": "list_links_hospitality_stock_store", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stock_store:read" ] } ], "summary": "List links of Stock store", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.stock_level_in_store", "hospitality.link.stock_store_at_property", "hospitality.link.stock_store_in_room" ] } } ] }, "/v1/object-types/hospitality.stock_store/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA place a house keeps stock: the stores room, a floor cupboard, the minibar cart, one room's minibar (linked `stock_store_in_room`), the laundry, the workshop. Keyed by `code` within the house; `define_stock_store` with a code the house holds re-states it in place. `is_default` marks the house's store of its kind that work draws from when it names none — a minibar task in a room with no minibar of its own draws from the default minibar cart, a laundry task from the default laundry, a fault's material line from the default workshop (one default per kind). A store's stock may go below zero only when it says so (`allow_negative`): a house that does not count its minibar carts lets them run negative rather than refuse a guest's charge.", "operationId": "traverse_hospitality_stock_store", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.stock_level_in_store", "hospitality.link.stock_store_at_property", "hospitality.link.stock_store_in_room" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stock_store:read" ] } ], "summary": "Traverse from Stock store", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.stock_store/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA place a house keeps stock: the stores room, a floor cupboard, the minibar cart, one room's minibar (linked `stock_store_in_room`), the laundry, the workshop. Keyed by `code` within the house; `define_stock_store` with a code the house holds re-states it in place. `is_default` marks the house's store of its kind that work draws from when it names none — a minibar task in a room with no minibar of its own draws from the default minibar cart, a laundry task from the default laundry, a fault's material line from the default workshop (one default per kind). A store's stock may go below zero only when it says so (`allow_negative`): a house that does not count its minibar carts lets them run negative rather than refuse a guest's charge.", "operationId": "search_hospitality_stock_store", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "main_store", "floor_store", "minibar_cart", "room_minibar", "laundry", "workshop" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "allow_negative" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "is_default" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "defined_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "defined_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "defined_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "kind", "defined_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stock_store" }, "properties": { "additionalProperties": false, "properties": { "allow_negative": { "title": "Whether its stock may go below zero (an uncounted store)", "type": "boolean" }, "code": { "title": "The house's code for the store — unique within the house", "type": "string" }, "defined_at": { "format": "date-time", "title": "When it was first defined", "type": "string" }, "is_default": { "title": "The house's store of its kind that work draws from when it names none", "type": "boolean" }, "kind": { "enum": [ "main_store", "floor_store", "minibar_cart", "room_minibar", "laundry", "workshop" ], "title": "main_store, floor_store, minibar_cart, room_minibar, laundry, workshop", "type": "string" }, "name": { "title": "The store in words (\"Stores\", \"Floor 3 linen\", \"Minibar 101\")", "type": "string" } }, "required": [ "code", "name", "kind", "allow_negative", "defined_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stock_store:read" ] } ], "summary": "Search Stock store", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.stored_object/objects/{id}": { "get": { "description": "Read an existing instance.\n\nTyped reference to a binary blob held in Aerandil's S3-compatible object storage. Holds the storage key, content type, size, and checksum — never the bytes, which are uploaded and downloaded directly via presigned URLs. The structural contract mirrors external_record_reference: a reference, never a payload.", "operationId": "get_hospitality_stored_object", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stored_object" }, "properties": { "additionalProperties": false, "properties": { "backend": { "enum": [ "s3" ], "title": "Storage backend", "type": "string" }, "bucket": { "title": "Bucket", "type": "string" }, "byte_size": { "title": "Verified size in bytes", "type": "integer" }, "checksum_sha256": { "title": "Verified SHA-256 (base64)", "type": "string" }, "content_category": { "enum": [ "identity_document", "contract", "invoice", "folio_document", "photo", "menu", "signature", "other" ], "title": "Content category", "type": "string" }, "content_type": { "title": "Content type (MIME)", "type": "string" }, "etag": { "title": "Storage ETag", "type": "string" }, "host_id": { "title": "Host entity id", "type": "string" }, "host_kind": { "enum": [ "person", "reservation", "property", "work_order", "room", "invoice", "checklist_result", "work_order_entry", "asset", "guest_feedback", "lost_found_item", "checkpoint_result", "housekeeping_task_entry" ], "title": "Host entity kind", "type": "string" }, "id": { "title": "Stored-object id", "type": "string" }, "max_bytes": { "title": "Declared maximum size in bytes", "type": "integer" }, "original_filename": { "title": "Original filename", "type": "string" }, "status": { "enum": [ "pending", "available", "deleted" ], "title": "Lifecycle status", "type": "string" }, "storage_key": { "title": "Storage key", "type": "string" }, "uploaded_at": { "format": "date-time", "title": "Upload confirmed at", "type": "string" } }, "required": [ "id", "backend", "content_type", "status", "host_kind", "host_id" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stored_object:read" ] } ], "summary": "Read Stored object", "tags": [ "stored_objects" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.stored_object/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nTyped reference to a binary blob held in Aerandil's S3-compatible object storage. Holds the storage key, content type, size, and checksum — never the bytes, which are uploaded and downloaded directly via presigned URLs. The structural contract mirrors external_record_reference: a reference, never a payload.", "operationId": "get_hospitality_stored_object_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.stored_object" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stored_object:read" ] } ], "summary": "Read Stored object as of a watermark", "tags": [ "stored_objects" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.stored_object/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nTyped reference to a binary blob held in Aerandil's S3-compatible object storage. Holds the storage key, content type, size, and checksum — never the bytes, which are uploaded and downloaded directly via presigned URLs. The structural contract mirrors external_record_reference: a reference, never a payload.", "operationId": "list_links_hospitality_stored_object", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stored_object:read" ] } ], "summary": "List links of Stored object", "tags": [ "stored_objects" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.stored_object_for_asset", "hospitality.link.stored_object_for_checklist_result", "hospitality.link.stored_object_for_checkpoint_result", "hospitality.link.stored_object_for_guest_feedback", "hospitality.link.stored_object_for_housekeeping_task_entry", "hospitality.link.stored_object_for_invoice", "hospitality.link.stored_object_for_lost_found_item", "hospitality.link.stored_object_for_person", "hospitality.link.stored_object_for_property", "hospitality.link.stored_object_for_reservation", "hospitality.link.stored_object_for_room", "hospitality.link.stored_object_for_work_order", "hospitality.link.stored_object_for_work_order_entry" ] } } ] }, "/v1/object-types/hospitality.stored_object/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nTyped reference to a binary blob held in Aerandil's S3-compatible object storage. Holds the storage key, content type, size, and checksum — never the bytes, which are uploaded and downloaded directly via presigned URLs. The structural contract mirrors external_record_reference: a reference, never a payload.", "operationId": "traverse_hospitality_stored_object", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.stored_object_for_asset", "hospitality.link.stored_object_for_checklist_result", "hospitality.link.stored_object_for_checkpoint_result", "hospitality.link.stored_object_for_guest_feedback", "hospitality.link.stored_object_for_housekeeping_task_entry", "hospitality.link.stored_object_for_invoice", "hospitality.link.stored_object_for_lost_found_item", "hospitality.link.stored_object_for_person", "hospitality.link.stored_object_for_property", "hospitality.link.stored_object_for_reservation", "hospitality.link.stored_object_for_room", "hospitality.link.stored_object_for_work_order", "hospitality.link.stored_object_for_work_order_entry" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stored_object:read" ] } ], "summary": "Traverse from Stored object", "tags": [ "stored_objects" ] } }, "/v1/object-types/hospitality.stored_object/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nTyped reference to a binary blob held in Aerandil's S3-compatible object storage. Holds the storage key, content type, size, and checksum — never the bytes, which are uploaded and downloaded directly via presigned URLs. The structural contract mirrors external_record_reference: a reference, never a payload.", "operationId": "search_hospitality_stored_object", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "storage_key" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "storage_key" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "storage_key" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "storage_key" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "backend" }, "type": { "const": "eq" }, "value": { "enum": [ "s3" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "bucket" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "bucket" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "bucket" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "bucket" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "content_type" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "content_type" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "content_type" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "content_type" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "pending", "available", "deleted" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "host_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "person", "reservation", "property", "work_order", "room", "invoice", "checklist_result", "work_order_entry", "asset", "guest_feedback", "lost_found_item", "checkpoint_result", "housekeeping_task_entry" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "host_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "host_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "host_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "host_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "content_category" }, "type": { "const": "eq" }, "value": { "enum": [ "identity_document", "contract", "invoice", "folio_document", "photo", "menu", "signature", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "original_filename" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "original_filename" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "original_filename" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "original_filename" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_bytes" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_bytes" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_bytes" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "byte_size" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "byte_size" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "byte_size" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checksum_sha256" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checksum_sha256" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checksum_sha256" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "checksum_sha256" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "etag" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "etag" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "etag" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "etag" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "uploaded_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "uploaded_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "uploaded_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "storage_key", "backend", "bucket", "content_type", "status", "host_kind", "host_id", "content_category", "original_filename", "max_bytes", "byte_size", "checksum_sha256", "etag", "uploaded_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.stored_object" }, "properties": { "additionalProperties": false, "properties": { "backend": { "enum": [ "s3" ], "title": "Storage backend", "type": "string" }, "bucket": { "title": "Bucket", "type": "string" }, "byte_size": { "title": "Verified size in bytes", "type": "integer" }, "checksum_sha256": { "title": "Verified SHA-256 (base64)", "type": "string" }, "content_category": { "enum": [ "identity_document", "contract", "invoice", "folio_document", "photo", "menu", "signature", "other" ], "title": "Content category", "type": "string" }, "content_type": { "title": "Content type (MIME)", "type": "string" }, "etag": { "title": "Storage ETag", "type": "string" }, "host_id": { "title": "Host entity id", "type": "string" }, "host_kind": { "enum": [ "person", "reservation", "property", "work_order", "room", "invoice", "checklist_result", "work_order_entry", "asset", "guest_feedback", "lost_found_item", "checkpoint_result", "housekeeping_task_entry" ], "title": "Host entity kind", "type": "string" }, "id": { "title": "Stored-object id", "type": "string" }, "max_bytes": { "title": "Declared maximum size in bytes", "type": "integer" }, "original_filename": { "title": "Original filename", "type": "string" }, "status": { "enum": [ "pending", "available", "deleted" ], "title": "Lifecycle status", "type": "string" }, "storage_key": { "title": "Storage key", "type": "string" }, "uploaded_at": { "format": "date-time", "title": "Upload confirmed at", "type": "string" } }, "required": [ "id", "backend", "content_type", "status", "host_kind", "host_id" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.stored_object:read" ] } ], "summary": "Search Stored object", "tags": [ "stored_objects" ] } }, "/v1/object-types/hospitality.tax_application/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne tax line applied to a `Charge`. Required for fiscal reporting and OTA tax-and-fee disclosure: a single charge typically has several (city tax, occupancy tax, VAT, resort fee), each with its own jurisdiction, rate, and computed amount.", "operationId": "get_hospitality_tax_application", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.tax_application" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "Tax amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Tax application amount", "type": "object" }, "basis_amount": { "description": "Basis amount taxed", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Tax application basis amount", "type": "object" }, "code": { "title": "Tax code", "type": "string" }, "id": { "title": "Tax application id", "type": "string" }, "inclusive": { "title": "Inclusive of charge amount", "type": "boolean" }, "jurisdiction": { "title": "Jurisdiction", "type": "string" }, "rate": { "format": "decimal", "title": "Rate (decimal, e.g. 0.10 = 10%)", "type": "string" } }, "required": [ "id", "code", "jurisdiction", "rate", "basis_amount", "amount", "inclusive" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.tax_application:read" ] } ], "summary": "Read Tax application", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.tax_application/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne tax line applied to a `Charge`. Required for fiscal reporting and OTA tax-and-fee disclosure: a single charge typically has several (city tax, occupancy tax, VAT, resort fee), each with its own jurisdiction, rate, and computed amount.", "operationId": "get_hospitality_tax_application_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.tax_application" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.tax_application:read" ] } ], "summary": "Read Tax application as of a watermark", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.tax_application/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne tax line applied to a `Charge`. Required for fiscal reporting and OTA tax-and-fee disclosure: a single charge typically has several (city tax, occupancy tax, VAT, resort fee), each with its own jurisdiction, rate, and computed amount.", "operationId": "list_links_hospitality_tax_application", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.tax_application:read" ] } ], "summary": "List links of Tax application", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.charge_has_tax_application" ] } } ] }, "/v1/object-types/hospitality.tax_application/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne tax line applied to a `Charge`. Required for fiscal reporting and OTA tax-and-fee disclosure: a single charge typically has several (city tax, occupancy tax, VAT, resort fee), each with its own jurisdiction, rate, and computed amount.", "operationId": "traverse_hospitality_tax_application", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.charge_has_tax_application" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.tax_application:read" ] } ], "summary": "Traverse from Tax application", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.tax_application/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne tax line applied to a `Charge`. Required for fiscal reporting and OTA tax-and-fee disclosure: a single charge typically has several (city tax, occupancy tax, VAT, resort fee), each with its own jurisdiction, rate, and computed amount.", "operationId": "search_hospitality_tax_application", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "jurisdiction" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "jurisdiction" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "jurisdiction" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "jurisdiction" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rate" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rate" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rate" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "basis_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "inclusive" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "code", "jurisdiction", "rate" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.tax_application" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "Tax amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Tax application amount", "type": "object" }, "basis_amount": { "description": "Basis amount taxed", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Tax application basis amount", "type": "object" }, "code": { "title": "Tax code", "type": "string" }, "id": { "title": "Tax application id", "type": "string" }, "inclusive": { "title": "Inclusive of charge amount", "type": "boolean" }, "jurisdiction": { "title": "Jurisdiction", "type": "string" }, "rate": { "format": "decimal", "title": "Rate (decimal, e.g. 0.10 = 10%)", "type": "string" } }, "required": [ "id", "code", "jurisdiction", "rate", "basis_amount", "amount", "inclusive" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.tax_application:read" ] } ], "summary": "Search Tax application", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.tax_exemption/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA reservation's exemption from named tax codes — a government or diplomatic guest's certificate on file. Every tax line the kernel derives for the booking (room nights, day use, retained payments) skips a rule whose code is listed, from the moment it is set until it is revoked; postings already made keep their tax, as an invoice already printed would.", "operationId": "get_hospitality_tax_exemption", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.tax_exemption" }, "properties": { "additionalProperties": false, "properties": { "description": { "title": "Operator-facing note", "type": "string" }, "exempt_codes": { "items": { "type": "string" }, "title": "The tax rule codes the booking is exempt from", "type": "array" }, "granted_at": { "format": "date-time", "title": "When the exemption was recorded", "type": "string" }, "id": { "title": "Tax exemption id", "type": "string" }, "reason": { "enum": [ "government", "diplomatic", "international_organisation", "other" ], "title": "Why the booking is exempt", "type": "string" }, "reference": { "title": "The exemption certificate or authority reference an auditor asks for", "type": "string" }, "revoked_at": { "format": "date-time", "title": "When the exemption stopped applying; absent = in force", "type": "string" } }, "required": [ "id", "reason", "reference", "exempt_codes", "granted_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.tax_exemption:read" ] } ], "summary": "Read Tax exemption", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.tax_exemption/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA reservation's exemption from named tax codes — a government or diplomatic guest's certificate on file. Every tax line the kernel derives for the booking (room nights, day use, retained payments) skips a rule whose code is listed, from the moment it is set until it is revoked; postings already made keep their tax, as an invoice already printed would.", "operationId": "get_hospitality_tax_exemption_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.tax_exemption" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.tax_exemption:read" ] } ], "summary": "Read Tax exemption as of a watermark", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.tax_exemption/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA reservation's exemption from named tax codes — a government or diplomatic guest's certificate on file. Every tax line the kernel derives for the booking (room nights, day use, retained payments) skips a rule whose code is listed, from the moment it is set until it is revoked; postings already made keep their tax, as an invoice already printed would.", "operationId": "list_links_hospitality_tax_exemption", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.tax_exemption:read" ] } ], "summary": "List links of Tax exemption", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.reservation_has_tax_exemption" ] } } ] }, "/v1/object-types/hospitality.tax_exemption/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA reservation's exemption from named tax codes — a government or diplomatic guest's certificate on file. Every tax line the kernel derives for the booking (room nights, day use, retained payments) skips a rule whose code is listed, from the moment it is set until it is revoked; postings already made keep their tax, as an invoice already printed would.", "operationId": "traverse_hospitality_tax_exemption", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.reservation_has_tax_exemption" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.tax_exemption:read" ] } ], "summary": "Traverse from Tax exemption", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.tax_exemption/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA reservation's exemption from named tax codes — a government or diplomatic guest's certificate on file. Every tax line the kernel derives for the booking (room nights, day use, retained payments) skips a rule whose code is listed, from the moment it is set until it is revoked; postings already made keep their tax, as an invoice already printed would.", "operationId": "search_hospitality_tax_exemption", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reason" }, "type": { "const": "eq" }, "value": { "enum": [ "government", "diplomatic", "international_organisation", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "exempt_codes" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "granted_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "granted_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "granted_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revoked_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revoked_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "revoked_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "reason", "reference", "granted_at", "revoked_at", "description" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.tax_exemption" }, "properties": { "additionalProperties": false, "properties": { "description": { "title": "Operator-facing note", "type": "string" }, "exempt_codes": { "items": { "type": "string" }, "title": "The tax rule codes the booking is exempt from", "type": "array" }, "granted_at": { "format": "date-time", "title": "When the exemption was recorded", "type": "string" }, "id": { "title": "Tax exemption id", "type": "string" }, "reason": { "enum": [ "government", "diplomatic", "international_organisation", "other" ], "title": "Why the booking is exempt", "type": "string" }, "reference": { "title": "The exemption certificate or authority reference an auditor asks for", "type": "string" }, "revoked_at": { "format": "date-time", "title": "When the exemption stopped applying; absent = in force", "type": "string" } }, "required": [ "id", "reason", "reference", "exempt_codes", "granted_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.tax_exemption:read" ] } ], "summary": "Search Tax exemption", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.tax_rule/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne property-authored tax rule: jurisdiction, what it applies to (a USALI bucket, one retained-payment `system_charge_kind`, or an F&B `tax_class` — exactly one), percent / flat-per-night / per-person basis, inclusive/exclusive posture, an optional long-stay reduced value, and an effective-date window. The night audit derives each room posting's `tax_application` lines from the rooms rules active on the audited business date; a forfeited deposit, cancellation fee or no-show charge is taxed only by a rule targeting its kind. Rules sharing a `code` and a target form a non-overlapping succession timeline (a rate change end-dates the predecessor and mints the successor).", "operationId": "get_hospitality_tax_rule", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.tax_rule" }, "properties": { "additionalProperties": false, "properties": { "adults_only": { "title": "`per_person_per_night` only: count adults and not children (absent = everyone in the room)", "type": "boolean" }, "basis": { "enum": [ "percent", "flat_per_night", "per_person_per_night" ], "title": "How the tax computes", "type": "string" }, "bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "USALI bucket whose charges this rule taxes. Absent on a rule that targets a retained-payment kind instead", "type": "string" }, "code": { "title": "Tax code — the rule's identity within the property; rules sharing a code form one succession timeline", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "effective_from": { "format": "date", "title": "First business date the rule applies (inclusive)", "type": "string" }, "effective_to": { "format": "date", "title": "Last business date the rule applies (inclusive); absent = open-ended", "type": "string" }, "flat_amount": { "description": "Amount per room night (`flat_per_night`) or per guest per night (`per_person_per_night`). Required on those bases, forbidden on percent rules", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Tax rule flat amount", "type": "object" }, "id": { "title": "Tax rule id", "type": "string" }, "inclusive": { "title": "Whether the tax lives inside the posted amount (VAT carve-out) or on top of it (US-style add-on)", "type": "boolean" }, "jurisdiction": { "title": "Taxing jurisdiction (e.g. `US-NY-NYC`, `DE`)", "type": "string" }, "rate": { "format": "decimal", "title": "Rate for `percent` rules (decimal in [0, 1]; 0.10 = 10%). Required on percent rules, forbidden on flat rules", "type": "string" }, "reduced_after_nights": { "title": "`percent` rooms rules only: from the night after this many nights of a continuous stay, the rule taxes only `reduced_value_share` of the night's value (the UK 28-day rule)", "type": "integer" }, "reduced_value_share": { "format": "decimal", "title": "The share of a long-stay night's value the rule still taxes (decimal in (0, 1]; 0.20 = the UK's 20% facilities minimum)", "type": "string" }, "system_charge_kind": { "enum": [ "forfeited_deposit", "cancellation_fee", "no_show_fee", "no_show_revenue" ], "title": "The retained payment this rule taxes (forfeited deposit, cancellation fee, no-show fee, no-show revenue) — what the house keeps for a stay that did not happen. Nothing taxes one of these unless a rule targets its kind. Percent and inclusive only", "type": "string" }, "tax_class": { "title": "The F&B tax class this rule taxes (an `item_class.tax_class` code — Standard, Cold food, Children's meal). Percent only. A check line takes every rule in force for its class on the check's business date", "type": "string" } }, "required": [ "id", "code", "jurisdiction", "basis", "inclusive", "effective_from" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.tax_rule:read" ] } ], "summary": "Read Tax rule", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.tax_rule/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne property-authored tax rule: jurisdiction, what it applies to (a USALI bucket, one retained-payment `system_charge_kind`, or an F&B `tax_class` — exactly one), percent / flat-per-night / per-person basis, inclusive/exclusive posture, an optional long-stay reduced value, and an effective-date window. The night audit derives each room posting's `tax_application` lines from the rooms rules active on the audited business date; a forfeited deposit, cancellation fee or no-show charge is taxed only by a rule targeting its kind. Rules sharing a `code` and a target form a non-overlapping succession timeline (a rate change end-dates the predecessor and mints the successor).", "operationId": "get_hospitality_tax_rule_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.tax_rule" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.tax_rule:read" ] } ], "summary": "Read Tax rule as of a watermark", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.tax_rule/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne property-authored tax rule: jurisdiction, what it applies to (a USALI bucket, one retained-payment `system_charge_kind`, or an F&B `tax_class` — exactly one), percent / flat-per-night / per-person basis, inclusive/exclusive posture, an optional long-stay reduced value, and an effective-date window. The night audit derives each room posting's `tax_application` lines from the rooms rules active on the audited business date; a forfeited deposit, cancellation fee or no-show charge is taxed only by a rule targeting its kind. Rules sharing a `code` and a target form a non-overlapping succession timeline (a rate change end-dates the predecessor and mints the successor).", "operationId": "list_links_hospitality_tax_rule", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.tax_rule:read" ] } ], "summary": "List links of Tax rule", "tags": [ "finance" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.tax_rule_at_property" ] } } ] }, "/v1/object-types/hospitality.tax_rule/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne property-authored tax rule: jurisdiction, what it applies to (a USALI bucket, one retained-payment `system_charge_kind`, or an F&B `tax_class` — exactly one), percent / flat-per-night / per-person basis, inclusive/exclusive posture, an optional long-stay reduced value, and an effective-date window. The night audit derives each room posting's `tax_application` lines from the rooms rules active on the audited business date; a forfeited deposit, cancellation fee or no-show charge is taxed only by a rule targeting its kind. Rules sharing a `code` and a target form a non-overlapping succession timeline (a rate change end-dates the predecessor and mints the successor).", "operationId": "traverse_hospitality_tax_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.tax_rule_at_property" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.tax_rule:read" ] } ], "summary": "Traverse from Tax rule", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.tax_rule/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne property-authored tax rule: jurisdiction, what it applies to (a USALI bucket, one retained-payment `system_charge_kind`, or an F&B `tax_class` — exactly one), percent / flat-per-night / per-person basis, inclusive/exclusive posture, an optional long-stay reduced value, and an effective-date window. The night audit derives each room posting's `tax_application` lines from the rooms rules active on the audited business date; a forfeited deposit, cancellation fee or no-show charge is taxed only by a rule targeting its kind. Rules sharing a `code` and a target form a non-overlapping succession timeline (a rate change end-dates the predecessor and mints the successor).", "operationId": "search_hospitality_tax_rule", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "jurisdiction" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "jurisdiction" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "jurisdiction" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "jurisdiction" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "bucket" }, "type": { "const": "eq" }, "value": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "system_charge_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "forfeited_deposit", "cancellation_fee", "no_show_fee", "no_show_revenue" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_class" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_class" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_class" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "tax_class" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "basis" }, "type": { "const": "eq" }, "value": { "enum": [ "percent", "flat_per_night", "per_person_per_night" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rate" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rate" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "rate" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "flat_amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "adults_only" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reduced_after_nights" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reduced_after_nights" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reduced_after_nights" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reduced_value_share" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reduced_value_share" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reduced_value_share" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "inclusive" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_from" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "effective_to" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "code", "jurisdiction", "bucket", "system_charge_kind", "tax_class", "basis", "rate", "reduced_after_nights", "reduced_value_share", "effective_from", "effective_to", "description" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.tax_rule" }, "properties": { "additionalProperties": false, "properties": { "adults_only": { "title": "`per_person_per_night` only: count adults and not children (absent = everyone in the room)", "type": "boolean" }, "basis": { "enum": [ "percent", "flat_per_night", "per_person_per_night" ], "title": "How the tax computes", "type": "string" }, "bucket": { "enum": [ "rooms", "food_beverage", "health_club_spa", "golf", "parking", "minibar", "other_operated", "minor_operated", "miscellaneous_income", "it_services", "retail" ], "title": "USALI bucket whose charges this rule taxes. Absent on a rule that targets a retained-payment kind instead", "type": "string" }, "code": { "title": "Tax code — the rule's identity within the property; rules sharing a code form one succession timeline", "type": "string" }, "description": { "title": "Operator-facing description", "type": "string" }, "effective_from": { "format": "date", "title": "First business date the rule applies (inclusive)", "type": "string" }, "effective_to": { "format": "date", "title": "Last business date the rule applies (inclusive); absent = open-ended", "type": "string" }, "flat_amount": { "description": "Amount per room night (`flat_per_night`) or per guest per night (`per_person_per_night`). Required on those bases, forbidden on percent rules", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Tax rule flat amount", "type": "object" }, "id": { "title": "Tax rule id", "type": "string" }, "inclusive": { "title": "Whether the tax lives inside the posted amount (VAT carve-out) or on top of it (US-style add-on)", "type": "boolean" }, "jurisdiction": { "title": "Taxing jurisdiction (e.g. `US-NY-NYC`, `DE`)", "type": "string" }, "rate": { "format": "decimal", "title": "Rate for `percent` rules (decimal in [0, 1]; 0.10 = 10%). Required on percent rules, forbidden on flat rules", "type": "string" }, "reduced_after_nights": { "title": "`percent` rooms rules only: from the night after this many nights of a continuous stay, the rule taxes only `reduced_value_share` of the night's value (the UK 28-day rule)", "type": "integer" }, "reduced_value_share": { "format": "decimal", "title": "The share of a long-stay night's value the rule still taxes (decimal in (0, 1]; 0.20 = the UK's 20% facilities minimum)", "type": "string" }, "system_charge_kind": { "enum": [ "forfeited_deposit", "cancellation_fee", "no_show_fee", "no_show_revenue" ], "title": "The retained payment this rule taxes (forfeited deposit, cancellation fee, no-show fee, no-show revenue) — what the house keeps for a stay that did not happen. Nothing taxes one of these unless a rule targets its kind. Percent and inclusive only", "type": "string" }, "tax_class": { "title": "The F&B tax class this rule taxes (an `item_class.tax_class` code — Standard, Cold food, Children's meal). Percent only. A check line takes every rule in force for its class on the check's business date", "type": "string" } }, "required": [ "id", "code", "jurisdiction", "basis", "inclusive", "effective_from" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.tax_rule:read" ] } ], "summary": "Search Tax rule", "tags": [ "finance" ] } }, "/v1/object-types/hospitality.training_cohort/objects/{id}": { "get": { "description": "Read an existing instance.\n\nAppend-only record of a single training run's composition for unlearning + audit. `shard_assignment` records the SISA shard → tenants map (Bourtoule et al. 2021) so an Article 17 erasure retrains only the affected shards; `manifest_hash` is the sha256 over the canonicalised manifest. `epsilon_budget` / `delta_budget` are recorded, never enforced (proposal 0026 §6).", "operationId": "get_hospitality_training_cohort", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.training_cohort" }, "properties": { "additionalProperties": false, "properties": { "assembled_at": { "format": "date-time", "title": "When the cohort was assembled", "type": "string" }, "delta_budget": { "format": "decimal", "title": "DP delta for this run (recorded, not enforced)", "type": "string" }, "epsilon_budget": { "format": "decimal", "title": "DP epsilon for this run (recorded, not enforced)", "type": "string" }, "exclusion_list_size": { "title": "Count of erased records explicitly excluded from this cohort", "type": "integer" }, "id": { "title": "Cohort id", "type": "string" }, "manifest_hash": { "title": "sha256 of the canonicalised cohort manifest", "type": "string" }, "model_card_uri": { "title": "Opaque pointer to the model card (the serving service owns the doc)", "type": "string" }, "model_name": { "title": "Model this cohort trained", "type": "string" }, "model_version": { "title": "Model version this run produced", "type": "integer" }, "run_id": { "title": "MLflow run id (uuid) — the lineage anchor back to training", "type": "string" }, "shard_assignment": { "title": "SISA shard id → tenants assigned to that shard" } }, "required": [ "id", "model_name", "model_version", "run_id", "assembled_at", "shard_assignment", "exclusion_list_size", "manifest_hash" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.training_cohort:read" ] } ], "summary": "Read Training cohort", "tags": [ "consent" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.training_cohort/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nAppend-only record of a single training run's composition for unlearning + audit. `shard_assignment` records the SISA shard → tenants map (Bourtoule et al. 2021) so an Article 17 erasure retrains only the affected shards; `manifest_hash` is the sha256 over the canonicalised manifest. `epsilon_budget` / `delta_budget` are recorded, never enforced (proposal 0026 §6).", "operationId": "get_hospitality_training_cohort_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.training_cohort" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.training_cohort:read" ] } ], "summary": "Read Training cohort as of a watermark", "tags": [ "consent" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.training_cohort/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nAppend-only record of a single training run's composition for unlearning + audit. `shard_assignment` records the SISA shard → tenants map (Bourtoule et al. 2021) so an Article 17 erasure retrains only the affected shards; `manifest_hash` is the sha256 over the canonicalised manifest. `epsilon_budget` / `delta_budget` are recorded, never enforced (proposal 0026 §6).", "operationId": "search_hospitality_training_cohort", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_version" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_version" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_version" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "run_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "run_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "run_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "run_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "assembled_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "assembled_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "assembled_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "shard_assignment" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "epsilon_budget" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "epsilon_budget" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "epsilon_budget" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delta_budget" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delta_budget" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delta_budget" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "exclusion_list_size" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "exclusion_list_size" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "exclusion_list_size" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "manifest_hash" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "manifest_hash" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "manifest_hash" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "manifest_hash" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_card_uri" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_card_uri" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_card_uri" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model_card_uri" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "model_name", "model_version", "run_id", "assembled_at", "epsilon_budget", "delta_budget", "exclusion_list_size", "manifest_hash", "model_card_uri" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.training_cohort" }, "properties": { "additionalProperties": false, "properties": { "assembled_at": { "format": "date-time", "title": "When the cohort was assembled", "type": "string" }, "delta_budget": { "format": "decimal", "title": "DP delta for this run (recorded, not enforced)", "type": "string" }, "epsilon_budget": { "format": "decimal", "title": "DP epsilon for this run (recorded, not enforced)", "type": "string" }, "exclusion_list_size": { "title": "Count of erased records explicitly excluded from this cohort", "type": "integer" }, "id": { "title": "Cohort id", "type": "string" }, "manifest_hash": { "title": "sha256 of the canonicalised cohort manifest", "type": "string" }, "model_card_uri": { "title": "Opaque pointer to the model card (the serving service owns the doc)", "type": "string" }, "model_name": { "title": "Model this cohort trained", "type": "string" }, "model_version": { "title": "Model version this run produced", "type": "integer" }, "run_id": { "title": "MLflow run id (uuid) — the lineage anchor back to training", "type": "string" }, "shard_assignment": { "title": "SISA shard id → tenants assigned to that shard" } }, "required": [ "id", "model_name", "model_version", "run_id", "assembled_at", "shard_assignment", "exclusion_list_size", "manifest_hash" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.training_cohort:read" ] } ], "summary": "Search Training cohort", "tags": [ "consent" ] } }, "/v1/object-types/hospitality.treatment_room/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA bookable treatment space under a spa venue — massage room, couples suite, facial room, salon station, class studio (Book4Time's Facility). `capacity` bounds how many appointments may overlap in it: 1 for a standard room, 2 for a couples suite, more for class-style studios. Occupancy is derived from appointment windows (including the pre/cleanup buffers), so the room carries no live floor status. Configuration: CRUD-authored, linked to its venue via treatment_room_at_venue; which services it can host is the declared-optional treatment_room_supports_service map.", "operationId": "get_hospitality_treatment_room", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.treatment_room" }, "properties": { "additionalProperties": false, "properties": { "active": { "title": "Active", "type": "boolean" }, "capacity": { "title": "Concurrent appointments the room admits (couples suite = 2)", "type": "integer" }, "code": { "title": "Room code", "type": "string" }, "description": { "title": "Description", "type": "string" }, "kind": { "enum": [ "massage_room", "couples_suite", "facial_room", "body_treatment_room", "hydrotherapy_room", "thermal_area", "salon_station", "nail_station", "studio", "relaxation_area", "other" ], "title": "Room kind", "type": "string" }, "name": { "title": "Room name", "type": "string" } }, "required": [ "code", "name", "kind", "capacity", "active" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.treatment_room:read" ] } ], "summary": "Read Treatment room", "tags": [ "spa" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.treatment_room/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA bookable treatment space under a spa venue — massage room, couples suite, facial room, salon station, class studio (Book4Time's Facility). `capacity` bounds how many appointments may overlap in it: 1 for a standard room, 2 for a couples suite, more for class-style studios. Occupancy is derived from appointment windows (including the pre/cleanup buffers), so the room carries no live floor status. Configuration: CRUD-authored, linked to its venue via treatment_room_at_venue; which services it can host is the declared-optional treatment_room_supports_service map.", "operationId": "get_hospitality_treatment_room_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.treatment_room" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.treatment_room:read" ] } ], "summary": "Read Treatment room as of a watermark", "tags": [ "spa" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.treatment_room/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA bookable treatment space under a spa venue — massage room, couples suite, facial room, salon station, class studio (Book4Time's Facility). `capacity` bounds how many appointments may overlap in it: 1 for a standard room, 2 for a couples suite, more for class-style studios. Occupancy is derived from appointment windows (including the pre/cleanup buffers), so the room carries no live floor status. Configuration: CRUD-authored, linked to its venue via treatment_room_at_venue; which services it can host is the declared-optional treatment_room_supports_service map.", "operationId": "list_links_hospitality_treatment_room", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.treatment_room:read" ] } ], "summary": "List links of Treatment room", "tags": [ "spa" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.appointment_in_treatment_room", "hospitality.link.treatment_room_at_venue", "hospitality.link.treatment_room_supports_service" ] } } ] }, "/v1/object-types/hospitality.treatment_room/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA bookable treatment space under a spa venue — massage room, couples suite, facial room, salon station, class studio (Book4Time's Facility). `capacity` bounds how many appointments may overlap in it: 1 for a standard room, 2 for a couples suite, more for class-style studios. Occupancy is derived from appointment windows (including the pre/cleanup buffers), so the room carries no live floor status. Configuration: CRUD-authored, linked to its venue via treatment_room_at_venue; which services it can host is the declared-optional treatment_room_supports_service map.", "operationId": "traverse_hospitality_treatment_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.appointment_in_treatment_room", "hospitality.link.treatment_room_at_venue", "hospitality.link.treatment_room_supports_service" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.treatment_room:read" ] } ], "summary": "Traverse from Treatment room", "tags": [ "spa" ] } }, "/v1/object-types/hospitality.treatment_room/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA bookable treatment space under a spa venue — massage room, couples suite, facial room, salon station, class studio (Book4Time's Facility). `capacity` bounds how many appointments may overlap in it: 1 for a standard room, 2 for a couples suite, more for class-style studios. Occupancy is derived from appointment windows (including the pre/cleanup buffers), so the room carries no live floor status. Configuration: CRUD-authored, linked to its venue via treatment_room_at_venue; which services it can host is the declared-optional treatment_room_supports_service map.", "operationId": "search_hospitality_treatment_room", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "massage_room", "couples_suite", "facial_room", "body_treatment_room", "hydrotherapy_room", "thermal_area", "salon_station", "nail_station", "studio", "relaxation_area", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "capacity" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "capacity" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "capacity" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "active" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "kind", "capacity", "description" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.treatment_room" }, "properties": { "additionalProperties": false, "properties": { "active": { "title": "Active", "type": "boolean" }, "capacity": { "title": "Concurrent appointments the room admits (couples suite = 2)", "type": "integer" }, "code": { "title": "Room code", "type": "string" }, "description": { "title": "Description", "type": "string" }, "kind": { "enum": [ "massage_room", "couples_suite", "facial_room", "body_treatment_room", "hydrotherapy_room", "thermal_area", "salon_station", "nail_station", "studio", "relaxation_area", "other" ], "title": "Room kind", "type": "string" }, "name": { "title": "Room name", "type": "string" } }, "required": [ "code", "name", "kind", "capacity", "active" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.treatment_room:read" ] } ], "summary": "Search Treatment room", "tags": [ "spa" ] } }, "/v1/object-types/hospitality.turnaway/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA request for rooms the house refused — the lost-demand record. Not a reservation and not a waitlist entry: nothing traverses a turnaway, so it holds no inventory. Carries the night asked for, the stay length, the instant the guest asked (`requested_at`, business time), why the desk said no (`reason`), the minimum stay in force if one was, the segment and channel when known, for a guest who declined the rate (`rate`, a regret) the rate quoted, and the booking engine's key for the browser that asked (`visitor_id`) when its tag read one. A revenue-management forecast reads turnaways beside sales to see the demand a full house or a restriction hid; without them it is forecasting from censored data. A regret's quoted rate is how it reads its own price back out of what it saw, and the visitor key — on the reservation too — is how it tells one shopper's earlier looks from a stranger's.", "operationId": "get_hospitality_turnaway", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.turnaway" }, "properties": { "additionalProperties": false, "properties": { "adults": { "title": "Adults asked for", "type": "integer" }, "arrival_date": { "format": "date", "title": "The arrival night asked for", "type": "string" }, "external_ref": { "title": "Replay key for the recording source (unique per tenant while present)", "type": "string" }, "id": { "title": "Turnaway id", "type": "string" }, "market_segment": { "enum": [ "transient", "group", "contract" ], "title": "Market segment of the demand, when the desk could tell", "type": "string" }, "min_stay_in_force": { "title": "The minimum stay posted for the arrival when the request was refused", "type": "integer" }, "nights": { "title": "Nights asked for", "type": "integer" }, "notes": { "title": "What the desk noted", "type": "string" }, "quoted_rate": { "description": "Rate quoted", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Turnaway quoted rate", "type": "object" }, "reason": { "enum": [ "sold_out", "min_stay", "closed", "rate", "other" ], "title": "Why the request was refused", "type": "string" }, "requested_at": { "format": "date-time", "title": "When the guest asked (business time; defaults to now)", "type": "string" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "Channel the request arrived through, when known", "type": "string" }, "visitor_id": { "title": "Booking engine visitor", "type": "string" } }, "required": [ "id", "requested_at", "arrival_date", "nights", "reason" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.turnaway:read" ] } ], "summary": "Read Turnaway", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.turnaway/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA request for rooms the house refused — the lost-demand record. Not a reservation and not a waitlist entry: nothing traverses a turnaway, so it holds no inventory. Carries the night asked for, the stay length, the instant the guest asked (`requested_at`, business time), why the desk said no (`reason`), the minimum stay in force if one was, the segment and channel when known, for a guest who declined the rate (`rate`, a regret) the rate quoted, and the booking engine's key for the browser that asked (`visitor_id`) when its tag read one. A revenue-management forecast reads turnaways beside sales to see the demand a full house or a restriction hid; without them it is forecasting from censored data. A regret's quoted rate is how it reads its own price back out of what it saw, and the visitor key — on the reservation too — is how it tells one shopper's earlier looks from a stranger's.", "operationId": "get_hospitality_turnaway_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.turnaway" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.turnaway:read" ] } ], "summary": "Read Turnaway as of a watermark", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.turnaway/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA request for rooms the house refused — the lost-demand record. Not a reservation and not a waitlist entry: nothing traverses a turnaway, so it holds no inventory. Carries the night asked for, the stay length, the instant the guest asked (`requested_at`, business time), why the desk said no (`reason`), the minimum stay in force if one was, the segment and channel when known, for a guest who declined the rate (`rate`, a regret) the rate quoted, and the booking engine's key for the browser that asked (`visitor_id`) when its tag read one. A revenue-management forecast reads turnaways beside sales to see the demand a full house or a restriction hid; without them it is forecasting from censored data. A regret's quoted rate is how it reads its own price back out of what it saw, and the visitor key — on the reservation too — is how it tells one shopper's earlier looks from a stranger's.", "operationId": "list_links_hospitality_turnaway", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.turnaway:read" ] } ], "summary": "List links of Turnaway", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.turnaway_for_guest", "hospitality.link.turnaway_for_property", "hospitality.link.turnaway_for_rate_plan", "hospitality.link.turnaway_for_room_type" ] } } ] }, "/v1/object-types/hospitality.turnaway/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA request for rooms the house refused — the lost-demand record. Not a reservation and not a waitlist entry: nothing traverses a turnaway, so it holds no inventory. Carries the night asked for, the stay length, the instant the guest asked (`requested_at`, business time), why the desk said no (`reason`), the minimum stay in force if one was, the segment and channel when known, for a guest who declined the rate (`rate`, a regret) the rate quoted, and the booking engine's key for the browser that asked (`visitor_id`) when its tag read one. A revenue-management forecast reads turnaways beside sales to see the demand a full house or a restriction hid; without them it is forecasting from censored data. A regret's quoted rate is how it reads its own price back out of what it saw, and the visitor key — on the reservation too — is how it tells one shopper's earlier looks from a stranger's.", "operationId": "traverse_hospitality_turnaway", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.turnaway_for_guest", "hospitality.link.turnaway_for_property", "hospitality.link.turnaway_for_rate_plan", "hospitality.link.turnaway_for_room_type" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.turnaway:read" ] } ], "summary": "Traverse from Turnaway", "tags": [ "booking" ] } }, "/v1/object-types/hospitality.turnaway/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA request for rooms the house refused — the lost-demand record. Not a reservation and not a waitlist entry: nothing traverses a turnaway, so it holds no inventory. Carries the night asked for, the stay length, the instant the guest asked (`requested_at`, business time), why the desk said no (`reason`), the minimum stay in force if one was, the segment and channel when known, for a guest who declined the rate (`rate`, a regret) the rate quoted, and the booking engine's key for the browser that asked (`visitor_id`) when its tag read one. A revenue-management forecast reads turnaways beside sales to see the demand a full house or a restriction hid; without them it is forecasting from censored data. A regret's quoted rate is how it reads its own price back out of what it saw, and the visitor key — on the reservation too — is how it tells one shopper's earlier looks from a stranger's.", "operationId": "search_hospitality_turnaway", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "arrival_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "arrival_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "arrival_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "nights" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "nights" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "nights" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reason" }, "type": { "const": "eq" }, "value": { "enum": [ "sold_out", "min_stay", "closed", "rate", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "min_stay_in_force" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "min_stay_in_force" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "min_stay_in_force" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "market_segment" }, "type": { "const": "eq" }, "value": { "enum": [ "transient", "group", "contract" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source" }, "type": { "const": "eq" }, "value": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "adults" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "adults" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "adults" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quoted_rate" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "visitor_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "visitor_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "visitor_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "visitor_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "requested_at", "arrival_date", "nights", "reason", "min_stay_in_force", "market_segment", "source", "adults", "visitor_id", "notes", "external_ref" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.turnaway" }, "properties": { "additionalProperties": false, "properties": { "adults": { "title": "Adults asked for", "type": "integer" }, "arrival_date": { "format": "date", "title": "The arrival night asked for", "type": "string" }, "external_ref": { "title": "Replay key for the recording source (unique per tenant while present)", "type": "string" }, "id": { "title": "Turnaway id", "type": "string" }, "market_segment": { "enum": [ "transient", "group", "contract" ], "title": "Market segment of the demand, when the desk could tell", "type": "string" }, "min_stay_in_force": { "title": "The minimum stay posted for the arrival when the request was refused", "type": "integer" }, "nights": { "title": "Nights asked for", "type": "integer" }, "notes": { "title": "What the desk noted", "type": "string" }, "quoted_rate": { "description": "Rate quoted", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Turnaway quoted rate", "type": "object" }, "reason": { "enum": [ "sold_out", "min_stay", "closed", "rate", "other" ], "title": "Why the request was refused", "type": "string" }, "requested_at": { "format": "date-time", "title": "When the guest asked (business time; defaults to now)", "type": "string" }, "source": { "enum": [ "direct_web", "direct_call", "property_direct", "ota", "gds", "wholesale", "corporate", "walk_in", "group_block", "agent", "loyalty" ], "title": "Channel the request arrived through, when known", "type": "string" }, "visitor_id": { "title": "Booking engine visitor", "type": "string" } }, "required": [ "id", "requested_at", "arrival_date", "nights", "reason" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.turnaway:read" ] } ], "summary": "Search Turnaway", "tags": [ "booking" ] } }, "/v1/object-types/hospitality.utility_ledger_entry/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne posted utility cost line (USALI 12 Schedule 9 — Energy, Water, and Waste), with the metered consumption when the invoice carries it. `category` is stamped from `kind` (the four Schedule 9 groupings); the consumption quantity/unit pair stays in its source unit. Immutable except the terminal void.", "operationId": "get_hospitality_utility_ledger_entry", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.utility_ledger_entry" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "Amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Utility ledger entry amount", "type": "object" }, "business_date": { "format": "date", "title": "Business date", "type": "string" }, "category": { "enum": [ "energy", "water_sewer", "waste", "contract_services" ], "title": "USALI Schedule 9 category", "type": "string" }, "consumption_quantity": { "format": "decimal", "title": "Metered consumption quantity", "type": "string" }, "consumption_unit": { "enum": [ "kwh", "mwh", "therm", "mmbtu", "gallon", "cubic_meter", "litre", "kilogram", "pound", "ton", "tonne", "cubic_yard", "other" ], "title": "Consumption unit", "type": "string" }, "external_ref": { "title": "External ref", "type": "string" }, "id": { "title": "Entry id", "type": "string" }, "kind": { "enum": [ "electricity", "natural_gas", "fuel_oil", "propane", "steam", "chilled_water", "renewable_electricity", "water", "sewer", "waste_landfill", "waste_recycling", "waste_organics", "waste_hazardous", "contract_services", "other" ], "title": "USALI Schedule 9 account", "type": "string" }, "period_end": { "format": "date", "title": "Billing-period end", "type": "string" }, "period_start": { "format": "date", "title": "Billing-period start", "type": "string" }, "posted_at": { "format": "date-time", "title": "Posted at", "type": "string" }, "source": { "enum": [ "invoice_import", "manual" ], "title": "Source", "type": "string" }, "voided": { "title": "Voided", "type": "boolean" } }, "required": [ "id", "kind", "category", "business_date", "source", "posted_at", "voided" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.utility_ledger_entry:read" ] } ], "summary": "Read Utility ledger entry", "tags": [ "eww" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.utility_ledger_entry/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne posted utility cost line (USALI 12 Schedule 9 — Energy, Water, and Waste), with the metered consumption when the invoice carries it. `category` is stamped from `kind` (the four Schedule 9 groupings); the consumption quantity/unit pair stays in its source unit. Immutable except the terminal void.", "operationId": "get_hospitality_utility_ledger_entry_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.utility_ledger_entry" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.utility_ledger_entry:read" ] } ], "summary": "Read Utility ledger entry as of a watermark", "tags": [ "eww" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.utility_ledger_entry/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne posted utility cost line (USALI 12 Schedule 9 — Energy, Water, and Waste), with the metered consumption when the invoice carries it. `category` is stamped from `kind` (the four Schedule 9 groupings); the consumption quantity/unit pair stays in its source unit. Immutable except the terminal void.", "operationId": "list_links_hospitality_utility_ledger_entry", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.utility_ledger_entry:read" ] } ], "summary": "List links of Utility ledger entry", "tags": [ "eww" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.utility_entry_at_property" ] } } ] }, "/v1/object-types/hospitality.utility_ledger_entry/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne posted utility cost line (USALI 12 Schedule 9 — Energy, Water, and Waste), with the metered consumption when the invoice carries it. `category` is stamped from `kind` (the four Schedule 9 groupings); the consumption quantity/unit pair stays in its source unit. Immutable except the terminal void.", "operationId": "traverse_hospitality_utility_ledger_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.utility_entry_at_property" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.utility_ledger_entry:read" ] } ], "summary": "Traverse from Utility ledger entry", "tags": [ "eww" ] } }, "/v1/object-types/hospitality.utility_ledger_entry/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne posted utility cost line (USALI 12 Schedule 9 — Energy, Water, and Waste), with the metered consumption when the invoice carries it. `category` is stamped from `kind` (the four Schedule 9 groupings); the consumption quantity/unit pair stays in its source unit. Immutable except the terminal void.", "operationId": "search_hospitality_utility_ledger_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "electricity", "natural_gas", "fuel_oil", "propane", "steam", "chilled_water", "renewable_electricity", "water", "sewer", "waste_landfill", "waste_recycling", "waste_organics", "waste_hazardous", "contract_services", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "category" }, "type": { "const": "eq" }, "value": { "enum": [ "energy", "water_sewer", "waste", "contract_services" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "amount" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "consumption_quantity" }, "type": { "const": "eq" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "consumption_quantity" }, "type": { "const": "gte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "consumption_quantity" }, "type": { "const": "lte" }, "value": { "format": "decimal", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "consumption_unit" }, "type": { "const": "eq" }, "value": { "enum": [ "kwh", "mwh", "therm", "mmbtu", "gallon", "cubic_meter", "litre", "kilogram", "pound", "ton", "tonne", "cubic_yard", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "business_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_start" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_start" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_start" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_end" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_end" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "period_end" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "source" }, "type": { "const": "eq" }, "value": { "enum": [ "invoice_import", "manual" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "posted_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "posted_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "posted_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "voided" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "kind", "category", "consumption_quantity", "consumption_unit", "business_date", "period_start", "period_end", "source", "external_ref", "posted_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.utility_ledger_entry" }, "properties": { "additionalProperties": false, "properties": { "amount": { "description": "Amount", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Utility ledger entry amount", "type": "object" }, "business_date": { "format": "date", "title": "Business date", "type": "string" }, "category": { "enum": [ "energy", "water_sewer", "waste", "contract_services" ], "title": "USALI Schedule 9 category", "type": "string" }, "consumption_quantity": { "format": "decimal", "title": "Metered consumption quantity", "type": "string" }, "consumption_unit": { "enum": [ "kwh", "mwh", "therm", "mmbtu", "gallon", "cubic_meter", "litre", "kilogram", "pound", "ton", "tonne", "cubic_yard", "other" ], "title": "Consumption unit", "type": "string" }, "external_ref": { "title": "External ref", "type": "string" }, "id": { "title": "Entry id", "type": "string" }, "kind": { "enum": [ "electricity", "natural_gas", "fuel_oil", "propane", "steam", "chilled_water", "renewable_electricity", "water", "sewer", "waste_landfill", "waste_recycling", "waste_organics", "waste_hazardous", "contract_services", "other" ], "title": "USALI Schedule 9 account", "type": "string" }, "period_end": { "format": "date", "title": "Billing-period end", "type": "string" }, "period_start": { "format": "date", "title": "Billing-period start", "type": "string" }, "posted_at": { "format": "date-time", "title": "Posted at", "type": "string" }, "source": { "enum": [ "invoice_import", "manual" ], "title": "Source", "type": "string" }, "voided": { "title": "Voided", "type": "boolean" } }, "required": [ "id", "kind", "category", "business_date", "source", "posted_at", "voided" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.utility_ledger_entry:read" ] } ], "summary": "Search Utility ledger entry", "tags": [ "eww" ] } }, "/v1/object-types/hospitality.venue/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA sub-area of a property: room block, restaurant, bar, spa, pool, ballroom, fitness centre, retail outlet, or activity desk. Multi-venue resorts typically have many; a boutique hotel may have one (the rooms block).", "operationId": "get_hospitality_venue", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" }, "properties": { "additionalProperties": false, "properties": { "capacity": { "title": "Capacity (integer; meaning declared by `capacity_basis`)", "type": "integer" }, "capacity_basis": { "enum": [ "concurrent", "throughput_per_hour", "seated_capacity", "per_session", "unspecified" ], "title": "Capacity basis (what `capacity` measures)", "type": "string" }, "code": { "title": "Venue code", "type": "string" }, "description": { "title": "Description", "type": "string" }, "kind": { "enum": [ "rooms", "restaurant", "bar", "lounge", "spa", "pool", "ballroom", "meeting_room", "retail", "fitness", "beach_club", "kids_club", "activity_desk", "parking", "other" ], "title": "Venue kind", "type": "string" }, "name": { "title": "Venue name", "type": "string" } }, "required": [ "code", "name", "kind" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.venue:read" ] } ], "summary": "Read Venue", "tags": [ "organization" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.venue/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA sub-area of a property: room block, restaurant, bar, spa, pool, ballroom, fitness centre, retail outlet, or activity desk. Multi-venue resorts typically have many; a boutique hotel may have one (the rooms block).", "operationId": "get_hospitality_venue_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.venue" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.venue:read" ] } ], "summary": "Read Venue as of a watermark", "tags": [ "organization" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.venue/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA sub-area of a property: room block, restaurant, bar, spa, pool, ballroom, fitness centre, retail outlet, or activity desk. Multi-venue resorts typically have many; a boutique hotel may have one (the rooms block).", "operationId": "list_links_hospitality_venue", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.venue:read" ] } ], "summary": "List links of Venue", "tags": [ "organization" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.asset_at_venue", "hospitality.link.federated_participation_for_venue", "hospitality.link.lineup_at_venue", "hospitality.link.outlet_at_venue", "hospitality.link.pattern_at_venue", "hospitality.link.person_frequents_venue", "hospitality.link.property_has_venue", "hospitality.link.recovery_event_in_venue", "hospitality.link.retail_product_available_at_venue", "hospitality.link.treatment_room_at_venue", "hospitality.link.venue_has_brand", "hospitality.link.venue_has_operator", "hospitality.link.venue_has_register", "hospitality.link.venue_has_service_item", "hospitality.link.venue_residency", "hospitality.link.venue_visit_at_venue", "hospitality.link.wellness_equipment_at_venue", "hospitality.link.wellness_modality_at_venue" ] } } ] }, "/v1/object-types/hospitality.venue/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA sub-area of a property: room block, restaurant, bar, spa, pool, ballroom, fitness centre, retail outlet, or activity desk. Multi-venue resorts typically have many; a boutique hotel may have one (the rooms block).", "operationId": "traverse_hospitality_venue", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.asset_at_venue", "hospitality.link.federated_participation_for_venue", "hospitality.link.lineup_at_venue", "hospitality.link.outlet_at_venue", "hospitality.link.pattern_at_venue", "hospitality.link.person_frequents_venue", "hospitality.link.property_has_venue", "hospitality.link.recovery_event_in_venue", "hospitality.link.retail_product_available_at_venue", "hospitality.link.treatment_room_at_venue", "hospitality.link.venue_has_brand", "hospitality.link.venue_has_operator", "hospitality.link.venue_has_register", "hospitality.link.venue_has_service_item", "hospitality.link.venue_residency", "hospitality.link.venue_visit_at_venue", "hospitality.link.wellness_equipment_at_venue", "hospitality.link.wellness_modality_at_venue" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.venue:read" ] } ], "summary": "Traverse from Venue", "tags": [ "organization" ] } }, "/v1/object-types/hospitality.venue/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA sub-area of a property: room block, restaurant, bar, spa, pool, ballroom, fitness centre, retail outlet, or activity desk. Multi-venue resorts typically have many; a boutique hotel may have one (the rooms block).", "operationId": "search_hospitality_venue", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "rooms", "restaurant", "bar", "lounge", "spa", "pool", "ballroom", "meeting_room", "retail", "fitness", "beach_club", "kids_club", "activity_desk", "parking", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "capacity" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "capacity" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "capacity" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "capacity_basis" }, "type": { "const": "eq" }, "value": { "enum": [ "concurrent", "throughput_per_hour", "seated_capacity", "per_session", "unspecified" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "kind", "capacity", "capacity_basis", "description" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue" }, "properties": { "additionalProperties": false, "properties": { "capacity": { "title": "Capacity (integer; meaning declared by `capacity_basis`)", "type": "integer" }, "capacity_basis": { "enum": [ "concurrent", "throughput_per_hour", "seated_capacity", "per_session", "unspecified" ], "title": "Capacity basis (what `capacity` measures)", "type": "string" }, "code": { "title": "Venue code", "type": "string" }, "description": { "title": "Description", "type": "string" }, "kind": { "enum": [ "rooms", "restaurant", "bar", "lounge", "spa", "pool", "ballroom", "meeting_room", "retail", "fitness", "beach_club", "kids_club", "activity_desk", "parking", "other" ], "title": "Venue kind", "type": "string" }, "name": { "title": "Venue name", "type": "string" } }, "required": [ "code", "name", "kind" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.venue:read" ] } ], "summary": "Search Venue", "tags": [ "organization" ] } }, "/v1/object-types/hospitality.venue_brand/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA brand identity scoped to a venue, distinct from `brand` (the property/group-level brand). NoMad-the-restaurant, Cecconi's, Cowshed-the-spa, the Connaught Bar, Hélène Darroze — each carries positioning, target-customer mix, creative direction, and relationships to a parent brand (when one exists), a design DNA (when applicable), and an owning company (for white-label / third-party-owned venue brands like Hakkasan-the-brand). N:N with `venue` (Cecconi's at 15 locations; a multi-concept day-cafe/night-bar venue carries two concurrent brands) via the temporal `venue_has_brand` link.", "operationId": "get_hospitality_venue_brand", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue_brand" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Venue brand code", "type": "string" }, "creative_director": { "title": "Creative director", "type": "string" }, "description": { "title": "Description", "type": "string" }, "founded_date": { "format": "date", "title": "Founded on", "type": "string" }, "kind": { "enum": [ "restaurant", "bar", "lounge", "spa", "fitness_studio", "retail", "beach_club", "nightclub", "cafe", "multi_concept", "other" ], "title": "Venue brand kind", "type": "string" }, "name": { "title": "Venue brand name", "type": "string" }, "positioning": { "enum": [ "luxury", "upper_upscale", "upscale", "upper_midscale", "midscale", "economy", "boutique", "lifestyle" ], "title": "Market positioning", "type": "string" }, "sunset_date": { "format": "date", "title": "Sunset on (null when active)", "type": "string" }, "target_mix": { "enum": [ "locals_primary", "guests_primary", "balanced", "invitation_only" ], "title": "Target customer mix", "type": "string" }, "website_url": { "title": "Website URL", "type": "string" } }, "required": [ "code", "name", "kind", "target_mix" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.venue_brand:read" ] } ], "summary": "Read Venue brand", "tags": [ "brand_venue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.venue_brand/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA brand identity scoped to a venue, distinct from `brand` (the property/group-level brand). NoMad-the-restaurant, Cecconi's, Cowshed-the-spa, the Connaught Bar, Hélène Darroze — each carries positioning, target-customer mix, creative direction, and relationships to a parent brand (when one exists), a design DNA (when applicable), and an owning company (for white-label / third-party-owned venue brands like Hakkasan-the-brand). N:N with `venue` (Cecconi's at 15 locations; a multi-concept day-cafe/night-bar venue carries two concurrent brands) via the temporal `venue_has_brand` link.", "operationId": "get_hospitality_venue_brand_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.venue_brand" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.venue_brand:read" ] } ], "summary": "Read Venue brand as of a watermark", "tags": [ "brand_venue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.venue_brand/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA brand identity scoped to a venue, distinct from `brand` (the property/group-level brand). NoMad-the-restaurant, Cecconi's, Cowshed-the-spa, the Connaught Bar, Hélène Darroze — each carries positioning, target-customer mix, creative direction, and relationships to a parent brand (when one exists), a design DNA (when applicable), and an owning company (for white-label / third-party-owned venue brands like Hakkasan-the-brand). N:N with `venue` (Cecconi's at 15 locations; a multi-concept day-cafe/night-bar venue carries two concurrent brands) via the temporal `venue_has_brand` link.", "operationId": "list_links_hospitality_venue_brand", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.venue_brand:read" ] } ], "summary": "List links of Venue brand", "tags": [ "brand_venue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.retail_product_line_has_venue_brand_parent", "hospitality.link.venue_brand_has_design_dna", "hospitality.link.venue_brand_has_parent_brand", "hospitality.link.venue_brand_originated_at_property", "hospitality.link.venue_brand_owned_by_company", "hospitality.link.venue_has_brand" ] } } ] }, "/v1/object-types/hospitality.venue_brand/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA brand identity scoped to a venue, distinct from `brand` (the property/group-level brand). NoMad-the-restaurant, Cecconi's, Cowshed-the-spa, the Connaught Bar, Hélène Darroze — each carries positioning, target-customer mix, creative direction, and relationships to a parent brand (when one exists), a design DNA (when applicable), and an owning company (for white-label / third-party-owned venue brands like Hakkasan-the-brand). N:N with `venue` (Cecconi's at 15 locations; a multi-concept day-cafe/night-bar venue carries two concurrent brands) via the temporal `venue_has_brand` link.", "operationId": "traverse_hospitality_venue_brand", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.retail_product_line_has_venue_brand_parent", "hospitality.link.venue_brand_has_design_dna", "hospitality.link.venue_brand_has_parent_brand", "hospitality.link.venue_brand_originated_at_property", "hospitality.link.venue_brand_owned_by_company", "hospitality.link.venue_has_brand" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.venue_brand:read" ] } ], "summary": "Traverse from Venue brand", "tags": [ "brand_venue" ] } }, "/v1/object-types/hospitality.venue_brand/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA brand identity scoped to a venue, distinct from `brand` (the property/group-level brand). NoMad-the-restaurant, Cecconi's, Cowshed-the-spa, the Connaught Bar, Hélène Darroze — each carries positioning, target-customer mix, creative direction, and relationships to a parent brand (when one exists), a design DNA (when applicable), and an owning company (for white-label / third-party-owned venue brands like Hakkasan-the-brand). N:N with `venue` (Cecconi's at 15 locations; a multi-concept day-cafe/night-bar venue carries two concurrent brands) via the temporal `venue_has_brand` link.", "operationId": "search_hospitality_venue_brand", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "restaurant", "bar", "lounge", "spa", "fitness_studio", "retail", "beach_club", "nightclub", "cafe", "multi_concept", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_mix" }, "type": { "const": "eq" }, "value": { "enum": [ "locals_primary", "guests_primary", "balanced", "invitation_only" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "positioning" }, "type": { "const": "eq" }, "value": { "enum": [ "luxury", "upper_upscale", "upscale", "upper_midscale", "midscale", "economy", "boutique", "lifestyle" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "creative_director" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "creative_director" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "creative_director" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "creative_director" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "founded_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "founded_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "founded_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sunset_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sunset_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "sunset_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "website_url" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "website_url" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "website_url" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "website_url" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "kind", "target_mix", "positioning", "creative_director", "founded_date", "sunset_date", "description", "website_url" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue_brand" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Venue brand code", "type": "string" }, "creative_director": { "title": "Creative director", "type": "string" }, "description": { "title": "Description", "type": "string" }, "founded_date": { "format": "date", "title": "Founded on", "type": "string" }, "kind": { "enum": [ "restaurant", "bar", "lounge", "spa", "fitness_studio", "retail", "beach_club", "nightclub", "cafe", "multi_concept", "other" ], "title": "Venue brand kind", "type": "string" }, "name": { "title": "Venue brand name", "type": "string" }, "positioning": { "enum": [ "luxury", "upper_upscale", "upscale", "upper_midscale", "midscale", "economy", "boutique", "lifestyle" ], "title": "Market positioning", "type": "string" }, "sunset_date": { "format": "date", "title": "Sunset on (null when active)", "type": "string" }, "target_mix": { "enum": [ "locals_primary", "guests_primary", "balanced", "invitation_only" ], "title": "Target customer mix", "type": "string" }, "website_url": { "title": "Website URL", "type": "string" } }, "required": [ "code", "name", "kind", "target_mix" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.venue_brand:read" ] } ], "summary": "Search Venue brand", "tags": [ "brand_venue" ] } }, "/v1/object-types/hospitality.venue_visit/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA non-reservation visit to a venue by a person — a regular at the Connaught Bar who isn't staying at the hotel that night, a local who pops into Cecconi's for lunch every Wednesday, an out-of-town visitor who stopped in once and tipped well. The bar host's book turning into structured data. Pairs with `recognition_event` from proposal 0003 — visits are the substrate that recognition events are recorded against, but not every visit produces a typed recognition gesture.", "operationId": "get_hospitality_venue_visit", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue_visit" }, "properties": { "additionalProperties": false, "properties": { "arrived_at": { "format": "date-time", "title": "Arrived at", "type": "string" }, "covers_count": { "title": "Covers count (F&B venues)", "type": "integer" }, "departed_at": { "format": "date-time", "title": "Departed at", "type": "string" }, "host_recogniser": { "title": "Host / maître d' / bartender principal identifier", "type": "string" }, "host_stand_notes": { "title": "Host stand notes (preferences, usuals, observations)", "type": "string" }, "id": { "title": "Venue visit id", "type": "string" }, "notes": { "title": "Free-form host notes", "type": "string" }, "observed_companions_text": { "title": "Observed companions (free text — see §11 open question 6)", "type": "string" }, "party_size": { "title": "Party size", "type": "integer" }, "seated_at_text": { "title": "Seating location", "type": "string" }, "visited_on": { "format": "date", "title": "Visit date (venue local timezone)", "type": "string" } }, "required": [ "id", "visited_on" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.venue_visit:read" ] } ], "summary": "Read Venue visit", "tags": [ "brand_venue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.venue_visit/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA non-reservation visit to a venue by a person — a regular at the Connaught Bar who isn't staying at the hotel that night, a local who pops into Cecconi's for lunch every Wednesday, an out-of-town visitor who stopped in once and tipped well. The bar host's book turning into structured data. Pairs with `recognition_event` from proposal 0003 — visits are the substrate that recognition events are recorded against, but not every visit produces a typed recognition gesture.", "operationId": "get_hospitality_venue_visit_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.venue_visit" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.venue_visit:read" ] } ], "summary": "Read Venue visit as of a watermark", "tags": [ "brand_venue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.venue_visit/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA non-reservation visit to a venue by a person — a regular at the Connaught Bar who isn't staying at the hotel that night, a local who pops into Cecconi's for lunch every Wednesday, an out-of-town visitor who stopped in once and tipped well. The bar host's book turning into structured data. Pairs with `recognition_event` from proposal 0003 — visits are the substrate that recognition events are recorded against, but not every visit produces a typed recognition gesture.", "operationId": "list_links_hospitality_venue_visit", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.venue_visit:read" ] } ], "summary": "List links of Venue visit", "tags": [ "brand_venue" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.venue_visit_at_venue", "hospitality.link.venue_visit_for_modality", "hospitality.link.venue_visit_for_person", "hospitality.link.venue_visit_references_external_record" ] } } ] }, "/v1/object-types/hospitality.venue_visit/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA non-reservation visit to a venue by a person — a regular at the Connaught Bar who isn't staying at the hotel that night, a local who pops into Cecconi's for lunch every Wednesday, an out-of-town visitor who stopped in once and tipped well. The bar host's book turning into structured data. Pairs with `recognition_event` from proposal 0003 — visits are the substrate that recognition events are recorded against, but not every visit produces a typed recognition gesture.", "operationId": "traverse_hospitality_venue_visit", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.venue_visit_at_venue", "hospitality.link.venue_visit_for_modality", "hospitality.link.venue_visit_for_person", "hospitality.link.venue_visit_references_external_record" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.venue_visit:read" ] } ], "summary": "Traverse from Venue visit", "tags": [ "brand_venue" ] } }, "/v1/object-types/hospitality.venue_visit/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA non-reservation visit to a venue by a person — a regular at the Connaught Bar who isn't staying at the hotel that night, a local who pops into Cecconi's for lunch every Wednesday, an out-of-town visitor who stopped in once and tipped well. The bar host's book turning into structured data. Pairs with `recognition_event` from proposal 0003 — visits are the substrate that recognition events are recorded against, but not every visit produces a typed recognition gesture.", "operationId": "search_hospitality_venue_visit", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "visited_on" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "visited_on" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "visited_on" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "host_recogniser" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "host_recogniser" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "host_recogniser" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "host_recogniser" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "seated_at_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "seated_at_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "seated_at_text" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "seated_at_text" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "party_size" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "party_size" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "party_size" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "observed_companions_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "observed_companions_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "host_stand_notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "host_stand_notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "arrived_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "arrived_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "arrived_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "departed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "departed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "departed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "covers_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "covers_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "covers_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "visited_on", "host_recogniser", "seated_at_text", "party_size", "observed_companions_text", "host_stand_notes", "arrived_at", "departed_at", "covers_count", "notes" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.venue_visit" }, "properties": { "additionalProperties": false, "properties": { "arrived_at": { "format": "date-time", "title": "Arrived at", "type": "string" }, "covers_count": { "title": "Covers count (F&B venues)", "type": "integer" }, "departed_at": { "format": "date-time", "title": "Departed at", "type": "string" }, "host_recogniser": { "title": "Host / maître d' / bartender principal identifier", "type": "string" }, "host_stand_notes": { "title": "Host stand notes (preferences, usuals, observations)", "type": "string" }, "id": { "title": "Venue visit id", "type": "string" }, "notes": { "title": "Free-form host notes", "type": "string" }, "observed_companions_text": { "title": "Observed companions (free text — see §11 open question 6)", "type": "string" }, "party_size": { "title": "Party size", "type": "integer" }, "seated_at_text": { "title": "Seating location", "type": "string" }, "visited_on": { "format": "date", "title": "Visit date (venue local timezone)", "type": "string" } }, "required": [ "id", "visited_on" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.venue_visit:read" ] } ], "summary": "Search Venue visit", "tags": [ "brand_venue" ] } }, "/v1/object-types/hospitality.waitlist_entry/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA reservation request the house could not take, waiting for inventory to free up. Not a reservation status and not a reservation: nothing traverses a waitlist entry, so it consumes no availability by construction. Carries the request (property, guest, room type, rate plan, dates, occupancy) so `accept_waitlist_entry` can replay it through the ordinary guarded create path, plus the wait's own bookkeeping — `reason` for turnaway analysis, `priority` tier and `requested_at` for the working order (tier, then FIFO within tier), and `telephone` for OPERA's call-to-confirm flow. An offer — the desk's, or the automation lane's matcher on a freed room-night — keeps the room-nights for the guest in the ledger's `blocked` count until `offer_deadline`, listing them in `held_nights` so accept, cancel, a lapse and expiry give back exactly what was held; a lapsed offer returns the entry to waiting and the matcher passes the room to the next. The night audit expires the entry two business days after its requested departure.", "operationId": "get_hospitality_waitlist_entry", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.waitlist_entry" }, "properties": { "additionalProperties": false, "properties": { "accepted_at": { "format": "date-time", "title": "When the entry became a reservation", "type": "string" }, "adults": { "title": "Adults", "type": "integer" }, "arrival_date": { "format": "date", "title": "Requested arrival", "type": "string" }, "cancel_reason": { "title": "Why the wait was withdrawn", "type": "string" }, "cancelled_at": { "format": "date-time", "title": "When the wait was withdrawn", "type": "string" }, "children": { "title": "Children", "type": "integer" }, "claim_token_hash": { "title": "SHA-256 of the current offer's claim-link secret", "type": "string" }, "claimed_at": { "format": "date-time", "title": "When the guest took the offer through its claim link", "type": "string" }, "departure_date": { "format": "date", "title": "Requested departure", "type": "string" }, "expired_at": { "format": "date-time", "title": "When the night audit aged the entry out", "type": "string" }, "guest_notice_note": { "title": "Why the guest was not sent the current offer, when they were not", "type": "string" }, "guest_notice_ref": { "format": "uuid", "title": "The outbound message that told the guest of the current offer", "type": "string", "x-aerandil-references": "hospitality.guest_message" }, "guest_notified_at": { "format": "date-time", "title": "When the current offer was sent to the guest", "type": "string" }, "held_nights": { "title": "The ledger nights the current offer holds (JSON array of dates)" }, "id": { "title": "Waitlist entry id", "type": "string" }, "notes": { "title": "Desk notes on the request", "type": "string" }, "offer_deadline": { "format": "date-time", "title": "When the current offer lapses and its held nights go back", "type": "string" }, "offer_lapsed_at": { "format": "date-time", "title": "When an offer last lapsed unanswered; the matcher passes over the entry after", "type": "string" }, "offer_notes": { "title": "What was offered on the last contact, and what the guest said", "type": "string" }, "offer_origin": { "enum": [ "desk", "matched" ], "title": "Who made the current offer: the desk, or the matcher on a freed room-night", "type": "string" }, "offered_at": { "format": "date-time", "title": "When the desk last reached the guest with an offer", "type": "string" }, "priority": { "enum": [ "high", "normal", "low" ], "title": "Priority tier (FIFO applies within a tier)", "type": "string" }, "quoted_rate": { "description": "Rate quoted when the request was taken (indicative only)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Waitlist entry quoted rate", "type": "object" }, "reason": { "enum": [ "sold_out", "room_type_unavailable", "rate_unavailable", "restriction", "guest_request" ], "title": "Why the request could not be booked", "type": "string" }, "requested_at": { "format": "date-time", "title": "When the guest asked (defaults to now; the FIFO key)", "type": "string" }, "status": { "enum": [ "waiting", "offered", "accepted", "cancelled", "expired" ], "title": "Status", "type": "string" }, "telephone": { "title": "Number to call when the room frees (the call-to-confirm flow)", "type": "string" } }, "required": [ "id", "status", "reason", "priority", "requested_at", "arrival_date", "departure_date", "adults" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.waitlist_entry:read" ] } ], "summary": "Read Waitlist entry", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.waitlist_entry/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA reservation request the house could not take, waiting for inventory to free up. Not a reservation status and not a reservation: nothing traverses a waitlist entry, so it consumes no availability by construction. Carries the request (property, guest, room type, rate plan, dates, occupancy) so `accept_waitlist_entry` can replay it through the ordinary guarded create path, plus the wait's own bookkeeping — `reason` for turnaway analysis, `priority` tier and `requested_at` for the working order (tier, then FIFO within tier), and `telephone` for OPERA's call-to-confirm flow. An offer — the desk's, or the automation lane's matcher on a freed room-night — keeps the room-nights for the guest in the ledger's `blocked` count until `offer_deadline`, listing them in `held_nights` so accept, cancel, a lapse and expiry give back exactly what was held; a lapsed offer returns the entry to waiting and the matcher passes the room to the next. The night audit expires the entry two business days after its requested departure.", "operationId": "get_hospitality_waitlist_entry_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.waitlist_entry" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.waitlist_entry:read" ] } ], "summary": "Read Waitlist entry as of a watermark", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.waitlist_entry/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA reservation request the house could not take, waiting for inventory to free up. Not a reservation status and not a reservation: nothing traverses a waitlist entry, so it consumes no availability by construction. Carries the request (property, guest, room type, rate plan, dates, occupancy) so `accept_waitlist_entry` can replay it through the ordinary guarded create path, plus the wait's own bookkeeping — `reason` for turnaway analysis, `priority` tier and `requested_at` for the working order (tier, then FIFO within tier), and `telephone` for OPERA's call-to-confirm flow. An offer — the desk's, or the automation lane's matcher on a freed room-night — keeps the room-nights for the guest in the ledger's `blocked` count until `offer_deadline`, listing them in `held_nights` so accept, cancel, a lapse and expiry give back exactly what was held; a lapsed offer returns the entry to waiting and the matcher passes the room to the next. The night audit expires the entry two business days after its requested departure.", "operationId": "list_links_hospitality_waitlist_entry", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.waitlist_entry:read" ] } ], "summary": "List links of Waitlist entry", "tags": [ "booking" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.waitlist_entry_became_reservation", "hospitality.link.waitlist_entry_for_guest", "hospitality.link.waitlist_entry_for_property", "hospitality.link.waitlist_entry_for_rate_plan", "hospitality.link.waitlist_entry_for_room_type" ] } } ] }, "/v1/object-types/hospitality.waitlist_entry/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA reservation request the house could not take, waiting for inventory to free up. Not a reservation status and not a reservation: nothing traverses a waitlist entry, so it consumes no availability by construction. Carries the request (property, guest, room type, rate plan, dates, occupancy) so `accept_waitlist_entry` can replay it through the ordinary guarded create path, plus the wait's own bookkeeping — `reason` for turnaway analysis, `priority` tier and `requested_at` for the working order (tier, then FIFO within tier), and `telephone` for OPERA's call-to-confirm flow. An offer — the desk's, or the automation lane's matcher on a freed room-night — keeps the room-nights for the guest in the ledger's `blocked` count until `offer_deadline`, listing them in `held_nights` so accept, cancel, a lapse and expiry give back exactly what was held; a lapsed offer returns the entry to waiting and the matcher passes the room to the next. The night audit expires the entry two business days after its requested departure.", "operationId": "traverse_hospitality_waitlist_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.waitlist_entry_became_reservation", "hospitality.link.waitlist_entry_for_guest", "hospitality.link.waitlist_entry_for_property", "hospitality.link.waitlist_entry_for_rate_plan", "hospitality.link.waitlist_entry_for_room_type" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.waitlist_entry:read" ] } ], "summary": "Traverse from Waitlist entry", "tags": [ "booking" ] } }, "/v1/object-types/hospitality.waitlist_entry/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA reservation request the house could not take, waiting for inventory to free up. Not a reservation status and not a reservation: nothing traverses a waitlist entry, so it consumes no availability by construction. Carries the request (property, guest, room type, rate plan, dates, occupancy) so `accept_waitlist_entry` can replay it through the ordinary guarded create path, plus the wait's own bookkeeping — `reason` for turnaway analysis, `priority` tier and `requested_at` for the working order (tier, then FIFO within tier), and `telephone` for OPERA's call-to-confirm flow. An offer — the desk's, or the automation lane's matcher on a freed room-night — keeps the room-nights for the guest in the ledger's `blocked` count until `offer_deadline`, listing them in `held_nights` so accept, cancel, a lapse and expiry give back exactly what was held; a lapsed offer returns the entry to waiting and the matcher passes the room to the next. The night audit expires the entry two business days after its requested departure.", "operationId": "search_hospitality_waitlist_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "waiting", "offered", "accepted", "cancelled", "expired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reason" }, "type": { "const": "eq" }, "value": { "enum": [ "sold_out", "room_type_unavailable", "rate_unavailable", "restriction", "guest_request" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "priority" }, "type": { "const": "eq" }, "value": { "enum": [ "high", "normal", "low" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requested_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "arrival_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "arrival_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "arrival_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "departure_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "departure_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "departure_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "adults" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "adults" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "adults" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "children" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "children" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "children" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "quoted_rate" }, "type": { "const": "eq" }, "value": { "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "telephone" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "telephone" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "telephone" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "telephone" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "offered_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "offered_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "offered_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "offer_notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "offer_notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "accepted_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "accepted_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "accepted_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancelled_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancelled_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancelled_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancel_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "cancel_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expired_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expired_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expired_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "offer_deadline" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "offer_deadline" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "offer_deadline" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "offer_origin" }, "type": { "const": "eq" }, "value": { "enum": [ "desk", "matched" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "held_nights" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "offer_lapsed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "offer_lapsed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "offer_lapsed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "guest_notified_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "guest_notified_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "guest_notified_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "guest_notice_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.guest_message" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "guest_notice_note" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "guest_notice_note" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "claim_token_hash" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "claim_token_hash" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "claim_token_hash" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "claim_token_hash" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "claimed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "claimed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "claimed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "status", "reason", "priority", "requested_at", "arrival_date", "departure_date", "adults", "children", "telephone", "notes", "offered_at", "offer_notes", "accepted_at", "cancelled_at", "cancel_reason", "expired_at", "offer_deadline", "offer_origin", "offer_lapsed_at", "guest_notified_at", "guest_notice_note", "claim_token_hash", "claimed_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.waitlist_entry" }, "properties": { "additionalProperties": false, "properties": { "accepted_at": { "format": "date-time", "title": "When the entry became a reservation", "type": "string" }, "adults": { "title": "Adults", "type": "integer" }, "arrival_date": { "format": "date", "title": "Requested arrival", "type": "string" }, "cancel_reason": { "title": "Why the wait was withdrawn", "type": "string" }, "cancelled_at": { "format": "date-time", "title": "When the wait was withdrawn", "type": "string" }, "children": { "title": "Children", "type": "integer" }, "claim_token_hash": { "title": "SHA-256 of the current offer's claim-link secret", "type": "string" }, "claimed_at": { "format": "date-time", "title": "When the guest took the offer through its claim link", "type": "string" }, "departure_date": { "format": "date", "title": "Requested departure", "type": "string" }, "expired_at": { "format": "date-time", "title": "When the night audit aged the entry out", "type": "string" }, "guest_notice_note": { "title": "Why the guest was not sent the current offer, when they were not", "type": "string" }, "guest_notice_ref": { "format": "uuid", "title": "The outbound message that told the guest of the current offer", "type": "string", "x-aerandil-references": "hospitality.guest_message" }, "guest_notified_at": { "format": "date-time", "title": "When the current offer was sent to the guest", "type": "string" }, "held_nights": { "title": "The ledger nights the current offer holds (JSON array of dates)" }, "id": { "title": "Waitlist entry id", "type": "string" }, "notes": { "title": "Desk notes on the request", "type": "string" }, "offer_deadline": { "format": "date-time", "title": "When the current offer lapses and its held nights go back", "type": "string" }, "offer_lapsed_at": { "format": "date-time", "title": "When an offer last lapsed unanswered; the matcher passes over the entry after", "type": "string" }, "offer_notes": { "title": "What was offered on the last contact, and what the guest said", "type": "string" }, "offer_origin": { "enum": [ "desk", "matched" ], "title": "Who made the current offer: the desk, or the matcher on a freed room-night", "type": "string" }, "offered_at": { "format": "date-time", "title": "When the desk last reached the guest with an offer", "type": "string" }, "priority": { "enum": [ "high", "normal", "low" ], "title": "Priority tier (FIFO applies within a tier)", "type": "string" }, "quoted_rate": { "description": "Rate quoted when the request was taken (indicative only)", "properties": { "amount": { "format": "decimal", "type": "string" }, "currency": { "format": "iso-4217", "type": "string" } }, "required": [ "amount", "currency" ], "title": "Waitlist entry quoted rate", "type": "object" }, "reason": { "enum": [ "sold_out", "room_type_unavailable", "rate_unavailable", "restriction", "guest_request" ], "title": "Why the request could not be booked", "type": "string" }, "requested_at": { "format": "date-time", "title": "When the guest asked (defaults to now; the FIFO key)", "type": "string" }, "status": { "enum": [ "waiting", "offered", "accepted", "cancelled", "expired" ], "title": "Status", "type": "string" }, "telephone": { "title": "Number to call when the room frees (the call-to-confirm flow)", "type": "string" } }, "required": [ "id", "status", "reason", "priority", "requested_at", "arrival_date", "departure_date", "adults" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.waitlist_entry:read" ] } ], "summary": "Search Waitlist entry", "tags": [ "booking" ] } }, "/v1/object-types/hospitality.wellness_equipment/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA physical instance of a wellness modality. Decoupled from the modality concept because operators carry portable equipment that moves between venues and equipment that supports multiple modalities. Operator-side maintenance discipline (serial, install, service cadence) lives on the equipment row for compliance reporting on regulated equipment (HBOT chambers, cryo units).", "operationId": "get_hospitality_wellness_equipment", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.wellness_equipment" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Equipment code", "type": "string" }, "installed_at": { "format": "date", "title": "Installed on", "type": "string" }, "is_portable": { "title": "Portable (doesn't carry a stable venue link)", "type": "boolean" }, "last_serviced_at": { "format": "date", "title": "Last service date", "type": "string" }, "manufacturer": { "title": "Manufacturer", "type": "string" }, "modality_ref": { "format": "uuid", "title": "Primary modality this equipment provides", "type": "string", "x-aerandil-references": "hospitality.wellness_modality" }, "model": { "title": "Model", "type": "string" }, "name": { "title": "Equipment name", "type": "string" }, "next_service_due": { "format": "date", "title": "Next service due (regulator inspection or maintenance)", "type": "string" }, "notes": { "title": "Operator notes", "type": "string" }, "serial_number": { "title": "Serial number", "type": "string" }, "service_cadence_days": { "title": "Service cadence (days)", "type": "integer" } }, "required": [ "code", "name", "modality_ref", "is_portable" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.wellness_equipment:read" ] } ], "summary": "Read Wellness equipment", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.wellness_equipment/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA physical instance of a wellness modality. Decoupled from the modality concept because operators carry portable equipment that moves between venues and equipment that supports multiple modalities. Operator-side maintenance discipline (serial, install, service cadence) lives on the equipment row for compliance reporting on regulated equipment (HBOT chambers, cryo units).", "operationId": "get_hospitality_wellness_equipment_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.wellness_equipment" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.wellness_equipment:read" ] } ], "summary": "Read Wellness equipment as of a watermark", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.wellness_equipment/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA physical instance of a wellness modality. Decoupled from the modality concept because operators carry portable equipment that moves between venues and equipment that supports multiple modalities. Operator-side maintenance discipline (serial, install, service cadence) lives on the equipment row for compliance reporting on regulated equipment (HBOT chambers, cryo units).", "operationId": "list_links_hospitality_wellness_equipment", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.wellness_equipment:read" ] } ], "summary": "List links of Wellness equipment", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.wellness_equipment_at_venue" ] } } ] }, "/v1/object-types/hospitality.wellness_equipment/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA physical instance of a wellness modality. Decoupled from the modality concept because operators carry portable equipment that moves between venues and equipment that supports multiple modalities. Operator-side maintenance discipline (serial, install, service cadence) lives on the equipment row for compliance reporting on regulated equipment (HBOT chambers, cryo units).", "operationId": "traverse_hospitality_wellness_equipment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.wellness_equipment_at_venue" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.wellness_equipment:read" ] } ], "summary": "Traverse from Wellness equipment", "tags": [ "membership" ] } }, "/v1/object-types/hospitality.wellness_equipment/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA physical instance of a wellness modality. Decoupled from the modality concept because operators carry portable equipment that moves between venues and equipment that supports multiple modalities. Operator-side maintenance discipline (serial, install, service cadence) lives on the equipment row for compliance reporting on regulated equipment (HBOT chambers, cryo units).", "operationId": "search_hospitality_wellness_equipment", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "modality_ref" }, "type": { "const": "eq" }, "value": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.wellness_modality" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "is_portable" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "serial_number" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "serial_number" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "serial_number" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "serial_number" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "manufacturer" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "manufacturer" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "manufacturer" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "manufacturer" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "model" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "installed_at" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "installed_at" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "installed_at" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_serviced_at" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_serviced_at" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_serviced_at" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_service_due" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_service_due" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_service_due" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "service_cadence_days" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "service_cadence_days" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "service_cadence_days" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "serial_number", "manufacturer", "model", "installed_at", "last_serviced_at", "next_service_due", "service_cadence_days", "notes" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.wellness_equipment" }, "properties": { "additionalProperties": false, "properties": { "code": { "title": "Equipment code", "type": "string" }, "installed_at": { "format": "date", "title": "Installed on", "type": "string" }, "is_portable": { "title": "Portable (doesn't carry a stable venue link)", "type": "boolean" }, "last_serviced_at": { "format": "date", "title": "Last service date", "type": "string" }, "manufacturer": { "title": "Manufacturer", "type": "string" }, "modality_ref": { "format": "uuid", "title": "Primary modality this equipment provides", "type": "string", "x-aerandil-references": "hospitality.wellness_modality" }, "model": { "title": "Model", "type": "string" }, "name": { "title": "Equipment name", "type": "string" }, "next_service_due": { "format": "date", "title": "Next service due (regulator inspection or maintenance)", "type": "string" }, "notes": { "title": "Operator notes", "type": "string" }, "serial_number": { "title": "Serial number", "type": "string" }, "service_cadence_days": { "title": "Service cadence (days)", "type": "integer" } }, "required": [ "code", "name", "modality_ref", "is_portable" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.wellness_equipment:read" ] } ], "summary": "Search Wellness equipment", "tags": [ "membership" ] } }, "/v1/object-types/hospitality.wellness_modality/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA type of wellness service available at one or more venues. Distinct from `service_item` because modalities carry licensing context, evidence-level metadata, and capacity-model classification that the POS-catalogue shape does not type. The `requires_medical_licensing` flag plus the assessment side's structural payload-empty contract (commit 5) is the legal-architecture seam — clinical records stay in the external system; Aerandil holds only the opaque pointer.", "operationId": "get_hospitality_wellness_modality", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.wellness_modality" }, "properties": { "additionalProperties": false, "properties": { "capacity_model": { "enum": [ "throughput", "slot", "session", "session_with_roster", "shared_zone" ], "title": "Capacity model", "type": "string" }, "code": { "title": "Modality code", "type": "string" }, "contraindications_text": { "title": "Operator's contraindications summary (not clinical screening)", "type": "string" }, "description": { "title": "Description", "type": "string" }, "evidence_level": { "enum": [ "well_evidenced", "emerging", "aesthetic_only" ], "title": "Evidence level (substantive-vs-gimmick filter)", "type": "string" }, "evidence_source_url": { "title": "Evidence source URL (when the operator cites a specific base)", "type": "string" }, "kind": { "enum": [ "cold_therapy", "heat_therapy", "contrast_therapy", "resistance_training", "cardiovascular", "mobility", "recovery_passive", "recovery_active", "diagnostic", "clinical_intervention", "mindfulness", "sleep_optimisation", "nutritional", "aesthetic", "other" ], "title": "Modality kind", "type": "string" }, "licensing_jurisdiction": { "title": "Licensing jurisdiction (free text — regulator authority)", "type": "string" }, "name": { "title": "Modality name", "type": "string" }, "requires_medical_licensing": { "title": "Booking requires external_record_reference (clinical seam)", "type": "boolean" }, "typical_duration_minutes": { "title": "Typical duration (minutes)", "type": "integer" } }, "required": [ "code", "name", "kind", "evidence_level", "capacity_model", "requires_medical_licensing" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.wellness_modality:read" ] } ], "summary": "Read Wellness modality", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.wellness_modality/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA type of wellness service available at one or more venues. Distinct from `service_item` because modalities carry licensing context, evidence-level metadata, and capacity-model classification that the POS-catalogue shape does not type. The `requires_medical_licensing` flag plus the assessment side's structural payload-empty contract (commit 5) is the legal-architecture seam — clinical records stay in the external system; Aerandil holds only the opaque pointer.", "operationId": "get_hospitality_wellness_modality_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.wellness_modality" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.wellness_modality:read" ] } ], "summary": "Read Wellness modality as of a watermark", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.wellness_modality/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA type of wellness service available at one or more venues. Distinct from `service_item` because modalities carry licensing context, evidence-level metadata, and capacity-model classification that the POS-catalogue shape does not type. The `requires_medical_licensing` flag plus the assessment side's structural payload-empty contract (commit 5) is the legal-architecture seam — clinical records stay in the external system; Aerandil holds only the opaque pointer.", "operationId": "list_links_hospitality_wellness_modality", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.wellness_modality:read" ] } ], "summary": "List links of Wellness modality", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.protocol_references_modalities", "hospitality.link.spa_service_for_modality", "hospitality.link.venue_visit_for_modality", "hospitality.link.wellness_modality_at_venue" ] } } ] }, "/v1/object-types/hospitality.wellness_modality/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA type of wellness service available at one or more venues. Distinct from `service_item` because modalities carry licensing context, evidence-level metadata, and capacity-model classification that the POS-catalogue shape does not type. The `requires_medical_licensing` flag plus the assessment side's structural payload-empty contract (commit 5) is the legal-architecture seam — clinical records stay in the external system; Aerandil holds only the opaque pointer.", "operationId": "traverse_hospitality_wellness_modality", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.protocol_references_modalities", "hospitality.link.spa_service_for_modality", "hospitality.link.venue_visit_for_modality", "hospitality.link.wellness_modality_at_venue" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.wellness_modality:read" ] } ], "summary": "Traverse from Wellness modality", "tags": [ "membership" ] } }, "/v1/object-types/hospitality.wellness_modality/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA type of wellness service available at one or more venues. Distinct from `service_item` because modalities carry licensing context, evidence-level metadata, and capacity-model classification that the POS-catalogue shape does not type. The `requires_medical_licensing` flag plus the assessment side's structural payload-empty contract (commit 5) is the legal-architecture seam — clinical records stay in the external system; Aerandil holds only the opaque pointer.", "operationId": "search_hospitality_wellness_modality", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "cold_therapy", "heat_therapy", "contrast_therapy", "resistance_training", "cardiovascular", "mobility", "recovery_passive", "recovery_active", "diagnostic", "clinical_intervention", "mindfulness", "sleep_optimisation", "nutritional", "aesthetic", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_level" }, "type": { "const": "eq" }, "value": { "enum": [ "well_evidenced", "emerging", "aesthetic_only" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "capacity_model" }, "type": { "const": "eq" }, "value": { "enum": [ "throughput", "slot", "session", "session_with_roster", "shared_zone" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "requires_medical_licensing" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "typical_duration_minutes" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "typical_duration_minutes" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "typical_duration_minutes" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "licensing_jurisdiction" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "licensing_jurisdiction" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "licensing_jurisdiction" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "licensing_jurisdiction" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contraindications_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contraindications_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_source_url" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_source_url" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_source_url" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "evidence_source_url" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "code", "name", "kind", "evidence_level", "capacity_model", "description", "typical_duration_minutes", "licensing_jurisdiction", "contraindications_text", "evidence_source_url" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.wellness_modality" }, "properties": { "additionalProperties": false, "properties": { "capacity_model": { "enum": [ "throughput", "slot", "session", "session_with_roster", "shared_zone" ], "title": "Capacity model", "type": "string" }, "code": { "title": "Modality code", "type": "string" }, "contraindications_text": { "title": "Operator's contraindications summary (not clinical screening)", "type": "string" }, "description": { "title": "Description", "type": "string" }, "evidence_level": { "enum": [ "well_evidenced", "emerging", "aesthetic_only" ], "title": "Evidence level (substantive-vs-gimmick filter)", "type": "string" }, "evidence_source_url": { "title": "Evidence source URL (when the operator cites a specific base)", "type": "string" }, "kind": { "enum": [ "cold_therapy", "heat_therapy", "contrast_therapy", "resistance_training", "cardiovascular", "mobility", "recovery_passive", "recovery_active", "diagnostic", "clinical_intervention", "mindfulness", "sleep_optimisation", "nutritional", "aesthetic", "other" ], "title": "Modality kind", "type": "string" }, "licensing_jurisdiction": { "title": "Licensing jurisdiction (free text — regulator authority)", "type": "string" }, "name": { "title": "Modality name", "type": "string" }, "requires_medical_licensing": { "title": "Booking requires external_record_reference (clinical seam)", "type": "boolean" }, "typical_duration_minutes": { "title": "Typical duration (minutes)", "type": "integer" } }, "required": [ "code", "name", "kind", "evidence_level", "capacity_model", "requires_medical_licensing" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.wellness_modality:read" ] } ], "summary": "Search Wellness modality", "tags": [ "membership" ] } }, "/v1/object-types/hospitality.wellness_protocol/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA prescribed pattern of modality sessions for a member. The non-clinical equivalent of a prescription. Distinct from `coaching_plan` because the protocol is a typed modality-pattern prescription (modality X, frequency Y, duration Z) and the coaching plan is a narrative trajectory. Both ship because operator practice observed treats them as separate.", "operationId": "get_hospitality_wellness_protocol", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.wellness_protocol" }, "properties": { "additionalProperties": false, "properties": { "completed_at": { "format": "date-time", "title": "Actual completion", "type": "string" }, "duration_weeks": { "title": "Protocol duration in weeks (null for open-ended)", "type": "integer" }, "frequency_per_week": { "title": "Sessions per week (0 admissible for one-off protocols)", "type": "integer" }, "goals_text": { "title": "Member's stated goals", "type": "string" }, "id": { "title": "Protocol id", "type": "string" }, "is_active": { "title": "Currently active (false on completion or early termination)", "type": "boolean" }, "prescribed_at": { "format": "date-time", "title": "When the protocol was prescribed", "type": "string" }, "prescribing_practitioner_text": { "title": "Practitioner who prescribed (free text — staff or contractor)", "type": "string" }, "progress_notes": { "title": "Operator's running notes on member adherence + response", "type": "string" }, "target_completion_date": { "format": "date", "title": "Target completion", "type": "string" } }, "required": [ "id", "prescribed_at", "frequency_per_week", "is_active" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.wellness_protocol:read" ] } ], "summary": "Read Wellness protocol", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.wellness_protocol/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA prescribed pattern of modality sessions for a member. The non-clinical equivalent of a prescription. Distinct from `coaching_plan` because the protocol is a typed modality-pattern prescription (modality X, frequency Y, duration Z) and the coaching plan is a narrative trajectory. Both ship because operator practice observed treats them as separate.", "operationId": "get_hospitality_wellness_protocol_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.wellness_protocol" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.wellness_protocol:read" ] } ], "summary": "Read Wellness protocol as of a watermark", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.wellness_protocol/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA prescribed pattern of modality sessions for a member. The non-clinical equivalent of a prescription. Distinct from `coaching_plan` because the protocol is a typed modality-pattern prescription (modality X, frequency Y, duration Z) and the coaching plan is a narrative trajectory. Both ship because operator practice observed treats them as separate.", "operationId": "list_links_hospitality_wellness_protocol", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.wellness_protocol:read" ] } ], "summary": "List links of Wellness protocol", "tags": [ "membership" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.coaching_plan_references_protocol", "hospitality.link.protocol_references_modalities", "hospitality.link.wellness_protocol_for_membership" ] } } ] }, "/v1/object-types/hospitality.wellness_protocol/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA prescribed pattern of modality sessions for a member. The non-clinical equivalent of a prescription. Distinct from `coaching_plan` because the protocol is a typed modality-pattern prescription (modality X, frequency Y, duration Z) and the coaching plan is a narrative trajectory. Both ship because operator practice observed treats them as separate.", "operationId": "traverse_hospitality_wellness_protocol", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.coaching_plan_references_protocol", "hospitality.link.protocol_references_modalities", "hospitality.link.wellness_protocol_for_membership" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.wellness_protocol:read" ] } ], "summary": "Traverse from Wellness protocol", "tags": [ "membership" ] } }, "/v1/object-types/hospitality.wellness_protocol/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA prescribed pattern of modality sessions for a member. The non-clinical equivalent of a prescription. Distinct from `coaching_plan` because the protocol is a typed modality-pattern prescription (modality X, frequency Y, duration Z) and the coaching plan is a narrative trajectory. Both ship because operator practice observed treats them as separate.", "operationId": "search_hospitality_wellness_protocol", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "prescribed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "prescribed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "prescribed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "frequency_per_week" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "frequency_per_week" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "frequency_per_week" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "duration_weeks" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "duration_weeks" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "duration_weeks" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "prescribing_practitioner_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "prescribing_practitioner_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "prescribing_practitioner_text" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "prescribing_practitioner_text" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "goals_text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "goals_text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "progress_notes" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "progress_notes" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_completion_date" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_completion_date" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_completion_date" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "is_active" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "prescribed_at", "frequency_per_week", "duration_weeks", "prescribing_practitioner_text", "goals_text", "progress_notes", "target_completion_date", "completed_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.wellness_protocol" }, "properties": { "additionalProperties": false, "properties": { "completed_at": { "format": "date-time", "title": "Actual completion", "type": "string" }, "duration_weeks": { "title": "Protocol duration in weeks (null for open-ended)", "type": "integer" }, "frequency_per_week": { "title": "Sessions per week (0 admissible for one-off protocols)", "type": "integer" }, "goals_text": { "title": "Member's stated goals", "type": "string" }, "id": { "title": "Protocol id", "type": "string" }, "is_active": { "title": "Currently active (false on completion or early termination)", "type": "boolean" }, "prescribed_at": { "format": "date-time", "title": "When the protocol was prescribed", "type": "string" }, "prescribing_practitioner_text": { "title": "Practitioner who prescribed (free text — staff or contractor)", "type": "string" }, "progress_notes": { "title": "Operator's running notes on member adherence + response", "type": "string" }, "target_completion_date": { "format": "date", "title": "Target completion", "type": "string" } }, "required": [ "id", "prescribed_at", "frequency_per_week", "is_active" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.wellness_protocol:read" ] } ], "summary": "Search Wellness protocol", "tags": [ "membership" ] } }, "/v1/object-types/hospitality.work_order/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA maintenance request, typically against a room or venue. Tracks severity (cosmetic through to safety) through an explicit lifecycle: assign, schedule, start, complete (with a resolution), void (with a reason). Whether the room is out of order while the order is open is never a flag here — it is a real `room_status_block` held via `work_order_holds_block`, minted through the same code path as `take_room_out_of_order` and released on completion. The order is a thread (2026-10-13): its `work_order_entry` lines log notes, time, parts, hand-offs, the postponement and the resolution; it may name the equipment it is for (`work_order_for_asset`, its id carried as `asset_id`) and the guest stay that reported it (`work_order_reported_by_stay`), and `postpone_work_order` defers it to a named date (`resume_work_order` brings it back when the date comes). A hand-off on the thread stamps `delegated_to_role` until the order closes. Since 2026-10-15 a fault is for a room (`work_order_for_room`) or a public area (`work_order_for_area`, `create_public_area_work_order`), never both; it may name the room `element` it is in and the `fault_type` it was raised from; and it carries its holder's id (`assignee_id`, or a worker group's `group_id`) beside the edge every assigning verb moves.", "operationId": "get_hospitality_work_order", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" }, "properties": { "additionalProperties": false, "properties": { "area_id": { "title": "The public area the fault is in (its object id) — the `work_order_for_area` edge's target; absent for a room's order", "type": "string" }, "asset_id": { "title": "The asset the order is for (its object id) — the `work_order_for_asset` edge's target; absent when the order names no equipment", "type": "string" }, "assignee_id": { "title": "The staff member who holds the order (its object id) — the `work_order_assigned_to` edge's target; written by every verb that moves the edge", "type": "string" }, "block_reason": { "title": "What the work is waiting on while blocked", "type": "string" }, "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "Category", "type": "string" }, "delegated_to_role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "The staff role the order was last handed to by a delegation line on its thread (present until it completes or is voided)", "type": "string" }, "description": { "title": "Description", "type": "string" }, "element": { "enum": [ "light", "air_conditioning", "curtain", "safe", "door", "television", "phone", "wardrobe", "shower", "mirror", "toilet", "pipework", "minibar", "electrical", "other" ], "title": "The room element the fault is in (light, air_conditioning, shower …) — the attendant's word for it; `category` is the trade that mends it", "type": "string" }, "fault_type_id": { "title": "The fault type the order was raised from (its object id) — the `work_order_of_fault_type` edge's target", "type": "string" }, "group_id": { "title": "The worker group that holds the order (its object id) — the `work_order_assigned_to_group` edge's target; never beside `assignee_id`", "type": "string" }, "id": { "title": "Work order id", "type": "string" }, "maintenance_plan_id": { "title": "The maintenance plan that raised this order (its object id); absent otherwise", "type": "string" }, "postpone_reason": { "title": "Why the order was postponed (present while postponed)", "type": "string" }, "postponed_until": { "format": "date", "title": "The date a postponed order is deferred to (present while postponed)", "type": "string" }, "postponed_until_at": { "format": "date-time", "title": "The instant the house's day reaches postponed_until (its local midnight) — when the standing sweep brings the order back with resume_work_order (present while postponed)", "type": "string" }, "reported_at": { "format": "date-time", "title": "Reported at", "type": "string" }, "reported_by_guest": { "title": "Whether a guest reported the fault — true when the order names the reporting stay (`work_order_reported_by_stay`) or the triaged guest message that raised it", "type": "boolean" }, "resolution": { "title": "What was actually done", "type": "string" }, "resolved_at": { "format": "date-time", "title": "Resolved at", "type": "string" }, "scheduled_for": { "format": "date", "title": "Date the work is committed to", "type": "string" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "title": "Severity", "type": "string" }, "started_at": { "format": "date-time", "title": "When the engineer started", "type": "string" }, "status": { "enum": [ "open", "scheduled", "in_progress", "blocked", "complete", "void", "postponed" ], "title": "Status", "type": "string" }, "title": { "title": "Title", "type": "string" }, "void_reason": { "title": "Why a voided order was withdrawn", "type": "string" } }, "required": [ "id", "title", "category", "severity", "status", "reported_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.work_order:read" ] } ], "summary": "Read Work order", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.work_order/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA maintenance request, typically against a room or venue. Tracks severity (cosmetic through to safety) through an explicit lifecycle: assign, schedule, start, complete (with a resolution), void (with a reason). Whether the room is out of order while the order is open is never a flag here — it is a real `room_status_block` held via `work_order_holds_block`, minted through the same code path as `take_room_out_of_order` and released on completion. The order is a thread (2026-10-13): its `work_order_entry` lines log notes, time, parts, hand-offs, the postponement and the resolution; it may name the equipment it is for (`work_order_for_asset`, its id carried as `asset_id`) and the guest stay that reported it (`work_order_reported_by_stay`), and `postpone_work_order` defers it to a named date (`resume_work_order` brings it back when the date comes). A hand-off on the thread stamps `delegated_to_role` until the order closes. Since 2026-10-15 a fault is for a room (`work_order_for_room`) or a public area (`work_order_for_area`, `create_public_area_work_order`), never both; it may name the room `element` it is in and the `fault_type` it was raised from; and it carries its holder's id (`assignee_id`, or a worker group's `group_id`) beside the edge every assigning verb moves.", "operationId": "get_hospitality_work_order_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.work_order" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.work_order:read" ] } ], "summary": "Read Work order as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.work_order/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA maintenance request, typically against a room or venue. Tracks severity (cosmetic through to safety) through an explicit lifecycle: assign, schedule, start, complete (with a resolution), void (with a reason). Whether the room is out of order while the order is open is never a flag here — it is a real `room_status_block` held via `work_order_holds_block`, minted through the same code path as `take_room_out_of_order` and released on completion. The order is a thread (2026-10-13): its `work_order_entry` lines log notes, time, parts, hand-offs, the postponement and the resolution; it may name the equipment it is for (`work_order_for_asset`, its id carried as `asset_id`) and the guest stay that reported it (`work_order_reported_by_stay`), and `postpone_work_order` defers it to a named date (`resume_work_order` brings it back when the date comes). A hand-off on the thread stamps `delegated_to_role` until the order closes. Since 2026-10-15 a fault is for a room (`work_order_for_room`) or a public area (`work_order_for_area`, `create_public_area_work_order`), never both; it may name the room `element` it is in and the `fault_type` it was raised from; and it carries its holder's id (`assignee_id`, or a worker group's `group_id`) beside the edge every assigning verb moves.", "operationId": "list_links_hospitality_work_order", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.work_order:read" ] } ], "summary": "List links of Work order", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.pattern_clusters_work_order", "hospitality.link.pattern_remediation_chained_action_target", "hospitality.link.stock_movement_for_work_order", "hospitality.link.stored_object_for_work_order", "hospitality.link.work_order_answers_feedback", "hospitality.link.work_order_assigned_to", "hospitality.link.work_order_assigned_to_group", "hospitality.link.work_order_entry_for_work_order", "hospitality.link.work_order_for_area", "hospitality.link.work_order_for_asset", "hospitality.link.work_order_for_room", "hospitality.link.work_order_from_checkpoint", "hospitality.link.work_order_from_maintenance_plan", "hospitality.link.work_order_from_round", "hospitality.link.work_order_from_triage", "hospitality.link.work_order_holds_block", "hospitality.link.work_order_of_fault_type", "hospitality.link.work_order_reported_by_stay" ] } } ] }, "/v1/object-types/hospitality.work_order/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA maintenance request, typically against a room or venue. Tracks severity (cosmetic through to safety) through an explicit lifecycle: assign, schedule, start, complete (with a resolution), void (with a reason). Whether the room is out of order while the order is open is never a flag here — it is a real `room_status_block` held via `work_order_holds_block`, minted through the same code path as `take_room_out_of_order` and released on completion. The order is a thread (2026-10-13): its `work_order_entry` lines log notes, time, parts, hand-offs, the postponement and the resolution; it may name the equipment it is for (`work_order_for_asset`, its id carried as `asset_id`) and the guest stay that reported it (`work_order_reported_by_stay`), and `postpone_work_order` defers it to a named date (`resume_work_order` brings it back when the date comes). A hand-off on the thread stamps `delegated_to_role` until the order closes. Since 2026-10-15 a fault is for a room (`work_order_for_room`) or a public area (`work_order_for_area`, `create_public_area_work_order`), never both; it may name the room `element` it is in and the `fault_type` it was raised from; and it carries its holder's id (`assignee_id`, or a worker group's `group_id`) beside the edge every assigning verb moves.", "operationId": "traverse_hospitality_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.pattern_clusters_work_order", "hospitality.link.pattern_remediation_chained_action_target", "hospitality.link.stock_movement_for_work_order", "hospitality.link.stored_object_for_work_order", "hospitality.link.work_order_answers_feedback", "hospitality.link.work_order_assigned_to", "hospitality.link.work_order_assigned_to_group", "hospitality.link.work_order_entry_for_work_order", "hospitality.link.work_order_for_area", "hospitality.link.work_order_for_asset", "hospitality.link.work_order_for_room", "hospitality.link.work_order_from_checkpoint", "hospitality.link.work_order_from_maintenance_plan", "hospitality.link.work_order_from_round", "hospitality.link.work_order_from_triage", "hospitality.link.work_order_holds_block", "hospitality.link.work_order_of_fault_type", "hospitality.link.work_order_reported_by_stay" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.work_order:read" ] } ], "summary": "Traverse from Work order", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.work_order/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA maintenance request, typically against a room or venue. Tracks severity (cosmetic through to safety) through an explicit lifecycle: assign, schedule, start, complete (with a resolution), void (with a reason). Whether the room is out of order while the order is open is never a flag here — it is a real `room_status_block` held via `work_order_holds_block`, minted through the same code path as `take_room_out_of_order` and released on completion. The order is a thread (2026-10-13): its `work_order_entry` lines log notes, time, parts, hand-offs, the postponement and the resolution; it may name the equipment it is for (`work_order_for_asset`, its id carried as `asset_id`) and the guest stay that reported it (`work_order_reported_by_stay`), and `postpone_work_order` defers it to a named date (`resume_work_order` brings it back when the date comes). A hand-off on the thread stamps `delegated_to_role` until the order closes. Since 2026-10-15 a fault is for a room (`work_order_for_room`) or a public area (`work_order_for_area`, `create_public_area_work_order`), never both; it may name the room `element` it is in and the `fault_type` it was raised from; and it carries its holder's id (`assignee_id`, or a worker group's `group_id`) beside the edge every assigning verb moves.", "operationId": "search_hospitality_work_order", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "title" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "title" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "title" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "title" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "category" }, "type": { "const": "eq" }, "value": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "severity" }, "type": { "const": "eq" }, "value": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "open", "scheduled", "in_progress", "blocked", "complete", "void", "postponed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reported_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reported_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reported_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "scheduled_for" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "scheduled_for" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "scheduled_for" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "block_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "block_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "resolved_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "resolved_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "resolved_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "resolution" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "resolution" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "void_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "void_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "maintenance_plan_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "maintenance_plan_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "maintenance_plan_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "maintenance_plan_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "postponed_until" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "postponed_until" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "postponed_until" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "postpone_reason" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "postpone_reason" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "postponed_until_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "postponed_until_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "postponed_until_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "reported_by_guest" }, "type": { "const": "eq" }, "value": { "type": "boolean" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "asset_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "asset_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "asset_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "asset_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delegated_to_role" }, "type": { "const": "eq" }, "value": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "element" }, "type": { "const": "eq" }, "value": { "enum": [ "light", "air_conditioning", "curtain", "safe", "door", "television", "phone", "wardrobe", "shower", "mirror", "toilet", "pipework", "minibar", "electrical", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fault_type_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fault_type_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fault_type_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "fault_type_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "area_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "area_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "area_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "area_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "assignee_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "assignee_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "assignee_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "assignee_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "group_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "group_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "group_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "group_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "title", "description", "category", "severity", "status", "reported_at", "scheduled_for", "started_at", "block_reason", "resolved_at", "resolution", "void_reason", "maintenance_plan_id", "postponed_until", "postpone_reason", "postponed_until_at", "asset_id", "delegated_to_role", "element", "fault_type_id", "area_id", "assignee_id", "group_id" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order" }, "properties": { "additionalProperties": false, "properties": { "area_id": { "title": "The public area the fault is in (its object id) — the `work_order_for_area` edge's target; absent for a room's order", "type": "string" }, "asset_id": { "title": "The asset the order is for (its object id) — the `work_order_for_asset` edge's target; absent when the order names no equipment", "type": "string" }, "assignee_id": { "title": "The staff member who holds the order (its object id) — the `work_order_assigned_to` edge's target; written by every verb that moves the edge", "type": "string" }, "block_reason": { "title": "What the work is waiting on while blocked", "type": "string" }, "category": { "enum": [ "hvac", "plumbing", "electrical", "furniture", "fixtures", "networking", "audio_visual", "structural", "exterior", "safety", "other" ], "title": "Category", "type": "string" }, "delegated_to_role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "The staff role the order was last handed to by a delegation line on its thread (present until it completes or is voided)", "type": "string" }, "description": { "title": "Description", "type": "string" }, "element": { "enum": [ "light", "air_conditioning", "curtain", "safe", "door", "television", "phone", "wardrobe", "shower", "mirror", "toilet", "pipework", "minibar", "electrical", "other" ], "title": "The room element the fault is in (light, air_conditioning, shower …) — the attendant's word for it; `category` is the trade that mends it", "type": "string" }, "fault_type_id": { "title": "The fault type the order was raised from (its object id) — the `work_order_of_fault_type` edge's target", "type": "string" }, "group_id": { "title": "The worker group that holds the order (its object id) — the `work_order_assigned_to_group` edge's target; never beside `assignee_id`", "type": "string" }, "id": { "title": "Work order id", "type": "string" }, "maintenance_plan_id": { "title": "The maintenance plan that raised this order (its object id); absent otherwise", "type": "string" }, "postpone_reason": { "title": "Why the order was postponed (present while postponed)", "type": "string" }, "postponed_until": { "format": "date", "title": "The date a postponed order is deferred to (present while postponed)", "type": "string" }, "postponed_until_at": { "format": "date-time", "title": "The instant the house's day reaches postponed_until (its local midnight) — when the standing sweep brings the order back with resume_work_order (present while postponed)", "type": "string" }, "reported_at": { "format": "date-time", "title": "Reported at", "type": "string" }, "reported_by_guest": { "title": "Whether a guest reported the fault — true when the order names the reporting stay (`work_order_reported_by_stay`) or the triaged guest message that raised it", "type": "boolean" }, "resolution": { "title": "What was actually done", "type": "string" }, "resolved_at": { "format": "date-time", "title": "Resolved at", "type": "string" }, "scheduled_for": { "format": "date", "title": "Date the work is committed to", "type": "string" }, "severity": { "enum": [ "cosmetic", "minor", "major", "blocking", "safety" ], "title": "Severity", "type": "string" }, "started_at": { "format": "date-time", "title": "When the engineer started", "type": "string" }, "status": { "enum": [ "open", "scheduled", "in_progress", "blocked", "complete", "void", "postponed" ], "title": "Status", "type": "string" }, "title": { "title": "Title", "type": "string" }, "void_reason": { "title": "Why a voided order was withdrawn", "type": "string" } }, "required": [ "id", "title", "category", "severity", "status", "reported_at" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.work_order:read" ] } ], "summary": "Search Work order", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.work_order_entry/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne line on a work order's thread — hubOS's fault logbook thread as typed data: a `note`, `work` (minutes spent), `material` (parts used), a `delegation` to another role, the `postponement` (written by postpone_work_order, with the date and reason) or the `resolution` (written by complete_work_order). Linked to its order (`work_order_entry_for_work_order`) and to the staff member who wrote it when one did (`work_order_entry_recorded_by`); `recorded_by` names the principal either way. Append-only: a correction is another line. Photos hang off an entry as attachments. The order's time and parts are the sum of its entries — a query, not a stored total.", "operationId": "get_hospitality_work_order_entry", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order_entry" }, "properties": { "additionalProperties": false, "properties": { "delegated_to_role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "The role the order is handed to (a delegation line)", "type": "string" }, "id": { "title": "Work order entry id", "type": "string" }, "kind": { "enum": [ "note", "work", "material", "delegation", "postponement", "resolution" ], "title": "What the line records: note, work, material, delegation, postponement, resolution", "type": "string" }, "materials": { "description": "Parts used: description, quantity, optionally a unit, and the catalogued material and store a consumed part came from", "items": { "properties": { "description": { "type": "string" }, "material_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "type": "string" }, "store_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.stock_store" }, "unit": { "type": "string" } }, "required": [ "quantity" ], "type": "object" }, "title": "Work order entry materials", "type": "array" }, "minutes_spent": { "title": "Time spent on the work this line logs, in minutes (at most a week per line)", "type": "integer" }, "postponed_until": { "format": "date", "title": "The date the order was postponed to (a postponement line)", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When the line was written — the handset's own time when it queued offline", "type": "string" }, "recorded_by": { "title": "The principal that wrote the line (`user:…`, `agent:…`, `service:…`, `system`)", "type": "string" }, "text": { "title": "The words on the line (required for a note, a postponement's reason, a resolution)", "type": "string" } }, "required": [ "id", "kind", "recorded_at", "recorded_by" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.work_order_entry:read" ] } ], "summary": "Read Work order entry", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.work_order_entry/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne line on a work order's thread — hubOS's fault logbook thread as typed data: a `note`, `work` (minutes spent), `material` (parts used), a `delegation` to another role, the `postponement` (written by postpone_work_order, with the date and reason) or the `resolution` (written by complete_work_order). Linked to its order (`work_order_entry_for_work_order`) and to the staff member who wrote it when one did (`work_order_entry_recorded_by`); `recorded_by` names the principal either way. Append-only: a correction is another line. Photos hang off an entry as attachments. The order's time and parts are the sum of its entries — a query, not a stored total.", "operationId": "get_hospitality_work_order_entry_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.work_order_entry" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.work_order_entry:read" ] } ], "summary": "Read Work order entry as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.work_order_entry/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne line on a work order's thread — hubOS's fault logbook thread as typed data: a `note`, `work` (minutes spent), `material` (parts used), a `delegation` to another role, the `postponement` (written by postpone_work_order, with the date and reason) or the `resolution` (written by complete_work_order). Linked to its order (`work_order_entry_for_work_order`) and to the staff member who wrote it when one did (`work_order_entry_recorded_by`); `recorded_by` names the principal either way. Append-only: a correction is another line. Photos hang off an entry as attachments. The order's time and parts are the sum of its entries — a query, not a stored total.", "operationId": "list_links_hospitality_work_order_entry", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.work_order_entry:read" ] } ], "summary": "List links of Work order entry", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.stored_object_for_work_order_entry", "hospitality.link.work_order_entry_for_work_order", "hospitality.link.work_order_entry_recorded_by" ] } } ] }, "/v1/object-types/hospitality.work_order_entry/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne line on a work order's thread — hubOS's fault logbook thread as typed data: a `note`, `work` (minutes spent), `material` (parts used), a `delegation` to another role, the `postponement` (written by postpone_work_order, with the date and reason) or the `resolution` (written by complete_work_order). Linked to its order (`work_order_entry_for_work_order`) and to the staff member who wrote it when one did (`work_order_entry_recorded_by`); `recorded_by` names the principal either way. Append-only: a correction is another line. Photos hang off an entry as attachments. The order's time and parts are the sum of its entries — a query, not a stored total.", "operationId": "traverse_hospitality_work_order_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.stored_object_for_work_order_entry", "hospitality.link.work_order_entry_for_work_order", "hospitality.link.work_order_entry_recorded_by" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.work_order_entry:read" ] } ], "summary": "Traverse from Work order entry", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.work_order_entry/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne line on a work order's thread — hubOS's fault logbook thread as typed data: a `note`, `work` (minutes spent), `material` (parts used), a `delegation` to another role, the `postponement` (written by postpone_work_order, with the date and reason) or the `resolution` (written by complete_work_order). Linked to its order (`work_order_entry_for_work_order`) and to the staff member who wrote it when one did (`work_order_entry_recorded_by`); `recorded_by` names the principal either way. Append-only: a correction is another line. Photos hang off an entry as attachments. The order's time and parts are the sum of its entries — a query, not a stored total.", "operationId": "search_hospitality_work_order_entry", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "kind" }, "type": { "const": "eq" }, "value": { "enum": [ "note", "work", "material", "delegation", "postponement", "resolution" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "text" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "text" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "minutes_spent" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "minutes_spent" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "minutes_spent" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "materials" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "description": { "type": "string" }, "material_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "type": "string" }, "store_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.stock_store" }, "unit": { "type": "string" } }, "required": [ "quantity" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delegated_to_role" }, "type": { "const": "eq" }, "value": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "postponed_until" }, "type": { "const": "eq" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "postponed_until" }, "type": { "const": "gte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "postponed_until" }, "type": { "const": "lte" }, "value": { "format": "date", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "recorded_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "kind", "text", "minutes_spent", "delegated_to_role", "postponed_until", "recorded_at", "recorded_by" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.work_order_entry" }, "properties": { "additionalProperties": false, "properties": { "delegated_to_role": { "enum": [ "front_office_agent", "front_office_supervisor", "concierge", "bell", "housekeeper", "housekeeping_supervisor", "engineer", "food_beverage_server", "food_beverage_manager", "chef", "spa_therapist", "spa_manager", "reservations_agent", "revenue_manager", "sales_manager", "manager_on_duty", "general_manager", "owner", "other", "runner" ], "title": "The role the order is handed to (a delegation line)", "type": "string" }, "id": { "title": "Work order entry id", "type": "string" }, "kind": { "enum": [ "note", "work", "material", "delegation", "postponement", "resolution" ], "title": "What the line records: note, work, material, delegation, postponement, resolution", "type": "string" }, "materials": { "description": "Parts used: description, quantity, optionally a unit, and the catalogued material and store a consumed part came from", "items": { "properties": { "description": { "type": "string" }, "material_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.material" }, "quantity": { "format": "decimal", "type": "string" }, "store_id": { "format": "uuid", "type": "string", "x-aerandil-references": "hospitality.stock_store" }, "unit": { "type": "string" } }, "required": [ "quantity" ], "type": "object" }, "title": "Work order entry materials", "type": "array" }, "minutes_spent": { "title": "Time spent on the work this line logs, in minutes (at most a week per line)", "type": "integer" }, "postponed_until": { "format": "date", "title": "The date the order was postponed to (a postponement line)", "type": "string" }, "recorded_at": { "format": "date-time", "title": "When the line was written — the handset's own time when it queued offline", "type": "string" }, "recorded_by": { "title": "The principal that wrote the line (`user:…`, `agent:…`, `service:…`, `system`)", "type": "string" }, "text": { "title": "The words on the line (required for a note, a postponement's reason, a resolution)", "type": "string" } }, "required": [ "id", "kind", "recorded_at", "recorded_by" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.work_order_entry:read" ] } ], "summary": "Search Work order entry", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.worker_group/objects/{id}": { "get": { "description": "Read an existing instance.\n\nA named group of staff at a house that work is assigned to — the third-floor runners, the public-areas team, the night maintenance crew (hubOS's workers groups and its valets by floor). `name` is unique among the house's groups (`define_worker_group` upserts by it); `department` says whose work it takes — a housekeeping task goes to a `housekeeping`, `public_areas` or `other` group, a work order to a `maintenance` or `other` one; `floors`, when given, are the floors it covers, and a task in a room or area on another floor is refused to it. Members are `worker_group_has_member` edges (`set_worker_group_members`). Work assigned to the group (`housekeeping_task_assigned_to_group`, `work_order_assigned_to_group`) is taken by the member who starts it; a staff member outside the group may not start it. A `retired` group takes no work, and its open work returns to the open board.", "operationId": "get_hospitality_worker_group", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.worker_group" }, "properties": { "additionalProperties": false, "properties": { "department": { "enum": [ "housekeeping", "maintenance", "public_areas", "other" ], "title": "Whose work the group takes: housekeeping, maintenance, public areas or other", "type": "string" }, "floors": { "items": { "type": "string" }, "title": "The floors the group covers, in the rooms' own words; absent: every floor", "type": "array" }, "name": { "title": "What the house calls the group (unique among its groups)", "type": "string" }, "retired_at": { "format": "date-time", "title": "When the group was retired (present while retired)", "type": "string" }, "status": { "enum": [ "active", "retired" ], "title": "Active (takes work) or retired", "type": "string" } }, "required": [ "name", "department", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.worker_group:read" ] } ], "summary": "Read Worker group", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.worker_group/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nA named group of staff at a house that work is assigned to — the third-floor runners, the public-areas team, the night maintenance crew (hubOS's workers groups and its valets by floor). `name` is unique among the house's groups (`define_worker_group` upserts by it); `department` says whose work it takes — a housekeeping task goes to a `housekeeping`, `public_areas` or `other` group, a work order to a `maintenance` or `other` one; `floors`, when given, are the floors it covers, and a task in a room or area on another floor is refused to it. Members are `worker_group_has_member` edges (`set_worker_group_members`). Work assigned to the group (`housekeeping_task_assigned_to_group`, `work_order_assigned_to_group`) is taken by the member who starts it; a staff member outside the group may not start it. A `retired` group takes no work, and its open work returns to the open board.", "operationId": "get_hospitality_worker_group_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.worker_group" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.worker_group:read" ] } ], "summary": "Read Worker group as of a watermark", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.worker_group/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nA named group of staff at a house that work is assigned to — the third-floor runners, the public-areas team, the night maintenance crew (hubOS's workers groups and its valets by floor). `name` is unique among the house's groups (`define_worker_group` upserts by it); `department` says whose work it takes — a housekeeping task goes to a `housekeeping`, `public_areas` or `other` group, a work order to a `maintenance` or `other` one; `floors`, when given, are the floors it covers, and a task in a room or area on another floor is refused to it. Members are `worker_group_has_member` edges (`set_worker_group_members`). Work assigned to the group (`housekeeping_task_assigned_to_group`, `work_order_assigned_to_group`) is taken by the member who starts it; a staff member outside the group may not start it. A `retired` group takes no work, and its open work returns to the open board.", "operationId": "list_links_hospitality_worker_group", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.worker_group:read" ] } ], "summary": "List links of Worker group", "tags": [ "operations" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.housekeeping_task_assigned_to_group", "hospitality.link.work_order_assigned_to_group", "hospitality.link.worker_group_has_member" ] } } ] }, "/v1/object-types/hospitality.worker_group/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nA named group of staff at a house that work is assigned to — the third-floor runners, the public-areas team, the night maintenance crew (hubOS's workers groups and its valets by floor). `name` is unique among the house's groups (`define_worker_group` upserts by it); `department` says whose work it takes — a housekeeping task goes to a `housekeeping`, `public_areas` or `other` group, a work order to a `maintenance` or `other` one; `floors`, when given, are the floors it covers, and a task in a room or area on another floor is refused to it. Members are `worker_group_has_member` edges (`set_worker_group_members`). Work assigned to the group (`housekeeping_task_assigned_to_group`, `work_order_assigned_to_group`) is taken by the member who starts it; a staff member outside the group may not start it. A `retired` group takes no work, and its open work returns to the open board.", "operationId": "traverse_hospitality_worker_group", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.housekeeping_task_assigned_to_group", "hospitality.link.work_order_assigned_to_group", "hospitality.link.worker_group_has_member" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.worker_group:read" ] } ], "summary": "Traverse from Worker group", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.worker_group/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nA named group of staff at a house that work is assigned to — the third-floor runners, the public-areas team, the night maintenance crew (hubOS's workers groups and its valets by floor). `name` is unique among the house's groups (`define_worker_group` upserts by it); `department` says whose work it takes — a housekeeping task goes to a `housekeeping`, `public_areas` or `other` group, a work order to a `maintenance` or `other` one; `floors`, when given, are the floors it covers, and a task in a room or area on another floor is refused to it. Members are `worker_group_has_member` edges (`set_worker_group_members`). Work assigned to the group (`housekeeping_task_assigned_to_group`, `work_order_assigned_to_group`) is taken by the member who starts it; a staff member outside the group may not start it. A `retired` group takes no work, and its open work returns to the open board.", "operationId": "search_hospitality_worker_group", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "department" }, "type": { "const": "eq" }, "value": { "enum": [ "housekeeping", "maintenance", "public_areas", "other" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "floors" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "active", "retired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "retired_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "name", "department", "status", "retired_at" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.worker_group" }, "properties": { "additionalProperties": false, "properties": { "department": { "enum": [ "housekeeping", "maintenance", "public_areas", "other" ], "title": "Whose work the group takes: housekeeping, maintenance, public areas or other", "type": "string" }, "floors": { "items": { "type": "string" }, "title": "The floors the group covers, in the rooms' own words; absent: every floor", "type": "array" }, "name": { "title": "What the house calls the group (unique among its groups)", "type": "string" }, "retired_at": { "format": "date-time", "title": "When the group was retired (present while retired)", "type": "string" }, "status": { "enum": [ "active", "retired" ], "title": "Active (takes work) or retired", "type": "string" } }, "required": [ "name", "department", "status" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.worker_group:read" ] } ], "summary": "Search Worker group", "tags": [ "operations" ] } }, "/v1/object-types/hospitality.workflow_definition/objects/{id}": { "get": { "description": "Read an existing instance.\n\nVersioned, declarative workflow template. A definition pins step graph, schemas, retry/timeout/compensation policies, and the `definition_hash` over the canonical JSON form so every run can prove what shape it executes. After `status = active` all step/schema/policy fields are immutable; changes create a new version (proposal 0020 §4.1).", "operationId": "get_hospitality_workflow_definition", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_definition" }, "properties": { "additionalProperties": false, "properties": { "changelog_note": { "title": "Human explanation for active/deprecated versions", "type": "string" }, "compensation_policy": { "enum": [ "none", "best_effort", "required_for_side_effects", "manual_only" ], "title": "How the definition handles compensation after a failed terminal run", "type": "string" }, "default_retry_policy": { "title": "Default retry settings inherited by steps unless overridden" }, "definition_hash": { "title": "SHA-256 over canonical JSON of the definition. Runs pin this value.", "type": "string" }, "deprecated_at": { "format": "date-time", "title": "Set when status becomes deprecated", "type": "string" }, "description": { "title": "Bounded to 2048 characters", "type": "string" }, "high_risk_policy": { "enum": [ "forbid_auto_apply", "require_gate", "allow_with_policy" ], "title": "How the definition treats steps with high `risk_tier`", "type": "string" }, "id": { "title": "Definition id", "type": "string" }, "input_schema": { "title": "JSON-Schema-shaped typed parameter contract for `start_workflow_run`" }, "output_schema": { "title": "JSON-Schema-shaped result contract for completed runs" }, "owner_principal": { "title": "`Principal::stable_id()` of the maintainer / service owning the definition", "type": "string" }, "published_at": { "format": "date-time", "title": "Set when draft becomes active", "type": "string" }, "status": { "enum": [ "draft", "active", "deprecated", "retired" ], "title": "Lifecycle status", "type": "string" }, "step_definitions": { "title": "Ordered step definitions per §4.1.1. Stored as JSON for v1 — the typed step-definition shape (step_key, step_type, depends_on, action_name, parameter_template, idempotency_scope, retry_policy, compensation, approval_policy, wait_policy, branch_policy, subworkflow_ref, external_task_kind, executor_policy, risk_tier) is enforced by the workflow_definition validators in commit 9." }, "timeout_policy": { "title": "Run-level timeout / expiry settings" }, "title": { "title": "Human-readable name", "type": "string" }, "trigger_kind": { "enum": [ "manual", "event", "schedule", "webhook", "agent_requested", "api" ], "title": "What kind of caller starts runs of this definition", "type": "string" }, "version": { "title": "Operator-controlled semantic version or date. Immutable after activation.", "type": "string" }, "workflow_key": { "title": "Stable key under the tenant namespace (e.g. `late_checkout_exception`)", "type": "string" } }, "required": [ "id", "workflow_key", "version", "status", "title", "trigger_kind", "input_schema", "step_definitions", "compensation_policy", "high_risk_policy", "definition_hash" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.workflow_definition:read" ] } ], "summary": "Read Workflow definition", "tags": [ "workflows" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.workflow_definition/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nVersioned, declarative workflow template. A definition pins step graph, schemas, retry/timeout/compensation policies, and the `definition_hash` over the canonical JSON form so every run can prove what shape it executes. After `status = active` all step/schema/policy fields are immutable; changes create a new version (proposal 0020 §4.1).", "operationId": "get_hospitality_workflow_definition_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.workflow_definition" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.workflow_definition:read" ] } ], "summary": "Read Workflow definition as of a watermark", "tags": [ "workflows" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.workflow_definition/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nVersioned, declarative workflow template. A definition pins step graph, schemas, retry/timeout/compensation policies, and the `definition_hash` over the canonical JSON form so every run can prove what shape it executes. After `status = active` all step/schema/policy fields are immutable; changes create a new version (proposal 0020 §4.1).", "operationId": "list_links_hospitality_workflow_definition", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.workflow_definition:read" ] } ], "summary": "List links of Workflow definition", "tags": [ "workflows" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.workflow_run_for_definition" ] } } ] }, "/v1/object-types/hospitality.workflow_definition/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nVersioned, declarative workflow template. A definition pins step graph, schemas, retry/timeout/compensation policies, and the `definition_hash` over the canonical JSON form so every run can prove what shape it executes. After `status = active` all step/schema/policy fields are immutable; changes create a new version (proposal 0020 §4.1).", "operationId": "traverse_hospitality_workflow_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.workflow_run_for_definition" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.workflow_definition:read" ] } ], "summary": "Traverse from Workflow definition", "tags": [ "workflows" ] } }, "/v1/object-types/hospitality.workflow_definition/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nVersioned, declarative workflow template. A definition pins step graph, schemas, retry/timeout/compensation policies, and the `definition_hash` over the canonical JSON form so every run can prove what shape it executes. After `status = active` all step/schema/policy fields are immutable; changes create a new version (proposal 0020 §4.1).", "operationId": "search_hospitality_workflow_definition", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "workflow_key" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "workflow_key" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "workflow_key" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "workflow_key" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "version" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "version" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "version" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "version" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "draft", "active", "deprecated", "retired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "title" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "title" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "title" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "title" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "description" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "trigger_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "manual", "event", "schedule", "webhook", "agent_requested", "api" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "input_schema" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "output_schema" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "step_definitions" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "default_retry_policy" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "timeout_policy" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "compensation_policy" }, "type": { "const": "eq" }, "value": { "enum": [ "none", "best_effort", "required_for_side_effects", "manual_only" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "high_risk_policy" }, "type": { "const": "eq" }, "value": { "enum": [ "forbid_auto_apply", "require_gate", "allow_with_policy" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "owner_principal" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "owner_principal" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "owner_principal" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "owner_principal" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "published_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "published_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "published_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "deprecated_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "deprecated_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "deprecated_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_hash" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_hash" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_hash" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_hash" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "changelog_note" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "changelog_note" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "workflow_key", "version", "status", "title", "description", "trigger_kind", "compensation_policy", "high_risk_policy", "owner_principal", "published_at", "deprecated_at", "definition_hash", "changelog_note" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_definition" }, "properties": { "additionalProperties": false, "properties": { "changelog_note": { "title": "Human explanation for active/deprecated versions", "type": "string" }, "compensation_policy": { "enum": [ "none", "best_effort", "required_for_side_effects", "manual_only" ], "title": "How the definition handles compensation after a failed terminal run", "type": "string" }, "default_retry_policy": { "title": "Default retry settings inherited by steps unless overridden" }, "definition_hash": { "title": "SHA-256 over canonical JSON of the definition. Runs pin this value.", "type": "string" }, "deprecated_at": { "format": "date-time", "title": "Set when status becomes deprecated", "type": "string" }, "description": { "title": "Bounded to 2048 characters", "type": "string" }, "high_risk_policy": { "enum": [ "forbid_auto_apply", "require_gate", "allow_with_policy" ], "title": "How the definition treats steps with high `risk_tier`", "type": "string" }, "id": { "title": "Definition id", "type": "string" }, "input_schema": { "title": "JSON-Schema-shaped typed parameter contract for `start_workflow_run`" }, "output_schema": { "title": "JSON-Schema-shaped result contract for completed runs" }, "owner_principal": { "title": "`Principal::stable_id()` of the maintainer / service owning the definition", "type": "string" }, "published_at": { "format": "date-time", "title": "Set when draft becomes active", "type": "string" }, "status": { "enum": [ "draft", "active", "deprecated", "retired" ], "title": "Lifecycle status", "type": "string" }, "step_definitions": { "title": "Ordered step definitions per §4.1.1. Stored as JSON for v1 — the typed step-definition shape (step_key, step_type, depends_on, action_name, parameter_template, idempotency_scope, retry_policy, compensation, approval_policy, wait_policy, branch_policy, subworkflow_ref, external_task_kind, executor_policy, risk_tier) is enforced by the workflow_definition validators in commit 9." }, "timeout_policy": { "title": "Run-level timeout / expiry settings" }, "title": { "title": "Human-readable name", "type": "string" }, "trigger_kind": { "enum": [ "manual", "event", "schedule", "webhook", "agent_requested", "api" ], "title": "What kind of caller starts runs of this definition", "type": "string" }, "version": { "title": "Operator-controlled semantic version or date. Immutable after activation.", "type": "string" }, "workflow_key": { "title": "Stable key under the tenant namespace (e.g. `late_checkout_exception`)", "type": "string" } }, "required": [ "id", "workflow_key", "version", "status", "title", "trigger_kind", "input_schema", "step_definitions", "compensation_policy", "high_risk_policy", "definition_hash" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.workflow_definition:read" ] } ], "summary": "Search Workflow definition", "tags": [ "workflows" ] } }, "/v1/object-types/hospitality.workflow_run/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne durable execution pinned to exactly one active definition version. `definition_hash` is copied at start so the run can prove the exact shape it executed even if the definition is later deprecated. `target_refs_snapshot` is a redacted convenience snapshot — graph traversal uses concrete `workflow_run_targets_*` links. The runner that advances steps is a separate proposal (§9.2).", "operationId": "get_hospitality_workflow_run", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_run" }, "properties": { "additionalProperties": false, "properties": { "compensation_summary": { "title": "Bounded compensation outcome", "type": "string" }, "completed_at": { "format": "date-time", "title": "Terminal success / failure / cancellation / compensation terminal", "type": "string" }, "contestability_ref": { "title": "External support / appeal reference for guest-impacting automated decisions", "type": "string" }, "correlation_id": { "title": "Root correlation id for event joins", "type": "string" }, "current_step_keys": { "items": { "type": "string" }, "title": "Active / waiting step keys for fast display", "type": "array" }, "definition_hash": { "title": "Copied from definition at start time. Drift rejects step execution.", "type": "string" }, "definition_id": { "title": "Workflow definition object id. Part of the durable idempotency key.", "type": "string" }, "delegated_agent_installation_id": { "title": "Set when an installed agent initiated the run; mirrors the `workflow_run_started_by_agent_installation` link target", "type": "string" }, "expires_at": { "format": "date-time", "title": "Run timeout", "type": "string" }, "failure_summary": { "title": "Bounded terminal failure summary; full details stay on step runs", "type": "string" }, "id": { "title": "Run id", "type": "string" }, "idempotency_key": { "title": "Key used to start the run", "type": "string" }, "initiated_by": { "title": "`Principal::stable_id()` of caller that started the run", "type": "string" }, "input_snapshot": { "title": "Frozen, redacted start input" }, "last_transition_at": { "format": "date-time", "title": "Updated on every lifecycle transition", "type": "string" }, "output_snapshot": { "title": "Frozen completion output" }, "request_fingerprint": { "title": "SHA-256 over canonical start request fields. Same run_key with a different fingerprint is rejected.", "type": "string" }, "run_key": { "title": "Host-supplied business / dedupe key. Immutable.", "type": "string" }, "started_at": { "format": "date-time", "title": "Wall-clock start", "type": "string" }, "status": { "enum": [ "pending", "running", "waiting_for_approval", "waiting_for_event", "waiting_for_retry", "completed", "failed_pending_compensation", "failed_terminal", "cancel_requested", "canceled", "expired", "compensating", "compensated", "compensation_failed" ], "title": "Lifecycle status", "type": "string" }, "target_refs_snapshot": { "description": "Frozen `{object_type, object_id}` targets requested at start. Convenience snapshot only — graph traversal uses concrete `workflow_run_targets_*` links and never embeds payloads.", "items": { "properties": { "object_id": { "type": "string" }, "object_type": { "type": "string" } }, "required": [ "object_type", "object_id" ], "type": "object" }, "title": "Workflow run target refs snapshot", "type": "array" }, "trigger_kind": { "enum": [ "manual", "event", "schedule", "webhook", "agent_requested", "api" ], "title": "Copied from start request or definition default", "type": "string" }, "workflow_key": { "title": "Copied from definition at start time", "type": "string" }, "workflow_version": { "title": "Copied from definition at start time", "type": "string" } }, "required": [ "id", "definition_id", "run_key", "workflow_key", "workflow_version", "definition_hash", "status", "trigger_kind", "input_snapshot", "request_fingerprint", "current_step_keys", "started_at", "last_transition_at", "correlation_id", "idempotency_key" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.workflow_run:read" ] } ], "summary": "Read Workflow run", "tags": [ "workflows" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.workflow_run/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne durable execution pinned to exactly one active definition version. `definition_hash` is copied at start so the run can prove the exact shape it executed even if the definition is later deprecated. `target_refs_snapshot` is a redacted convenience snapshot — graph traversal uses concrete `workflow_run_targets_*` links. The runner that advances steps is a separate proposal (§9.2).", "operationId": "get_hospitality_workflow_run_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.workflow_run" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.workflow_run:read" ] } ], "summary": "Read Workflow run as of a watermark", "tags": [ "workflows" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.workflow_run/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne durable execution pinned to exactly one active definition version. `definition_hash` is copied at start so the run can prove the exact shape it executed even if the definition is later deprecated. `target_refs_snapshot` is a redacted convenience snapshot — graph traversal uses concrete `workflow_run_targets_*` links. The runner that advances steps is a separate proposal (§9.2).", "operationId": "list_links_hospitality_workflow_run", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.workflow_run:read" ] } ], "summary": "List links of Workflow run", "tags": [ "workflows" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.federated_run_started_by_workflow", "hospitality.link.participant_dispatch_for_workflow_run", "hospitality.link.workflow_run_for_definition", "hospitality.link.workflow_run_started_by_agent_installation", "hospitality.link.workflow_run_targets_charge", "hospitality.link.workflow_run_targets_folio", "hospitality.link.workflow_run_targets_fraud_risk_assessment", "hospitality.link.workflow_run_targets_membership", "hospitality.link.workflow_run_targets_message_triage", "hospitality.link.workflow_run_targets_payment", "hospitality.link.workflow_run_targets_person", "hospitality.link.workflow_run_targets_rate_recommendation", "hospitality.link.workflow_run_targets_reservation", "hospitality.link.workflow_run_targets_restriction_recommendation", "hospitality.link.workflow_run_targets_room", "hospitality.link.workflow_run_targets_service_recovery_event", "hospitality.link.workflow_run_targets_staff_member", "hospitality.link.workflow_step_run_for_workflow_run" ] } } ] }, "/v1/object-types/hospitality.workflow_run/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne durable execution pinned to exactly one active definition version. `definition_hash` is copied at start so the run can prove the exact shape it executed even if the definition is later deprecated. `target_refs_snapshot` is a redacted convenience snapshot — graph traversal uses concrete `workflow_run_targets_*` links. The runner that advances steps is a separate proposal (§9.2).", "operationId": "traverse_hospitality_workflow_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.federated_run_started_by_workflow", "hospitality.link.participant_dispatch_for_workflow_run", "hospitality.link.workflow_run_for_definition", "hospitality.link.workflow_run_started_by_agent_installation", "hospitality.link.workflow_run_targets_charge", "hospitality.link.workflow_run_targets_folio", "hospitality.link.workflow_run_targets_fraud_risk_assessment", "hospitality.link.workflow_run_targets_membership", "hospitality.link.workflow_run_targets_message_triage", "hospitality.link.workflow_run_targets_payment", "hospitality.link.workflow_run_targets_person", "hospitality.link.workflow_run_targets_rate_recommendation", "hospitality.link.workflow_run_targets_reservation", "hospitality.link.workflow_run_targets_restriction_recommendation", "hospitality.link.workflow_run_targets_room", "hospitality.link.workflow_run_targets_service_recovery_event", "hospitality.link.workflow_run_targets_staff_member", "hospitality.link.workflow_step_run_for_workflow_run" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.workflow_run:read" ] } ], "summary": "Traverse from Workflow run", "tags": [ "workflows" ] } }, "/v1/object-types/hospitality.workflow_run/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne durable execution pinned to exactly one active definition version. `definition_hash` is copied at start so the run can prove the exact shape it executed even if the definition is later deprecated. `target_refs_snapshot` is a redacted convenience snapshot — graph traversal uses concrete `workflow_run_targets_*` links. The runner that advances steps is a separate proposal (§9.2).", "operationId": "search_hospitality_workflow_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "run_key" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "run_key" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "run_key" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "run_key" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "workflow_key" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "workflow_key" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "workflow_key" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "workflow_key" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "workflow_version" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "workflow_version" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "workflow_version" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "workflow_version" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_hash" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_hash" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_hash" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "definition_hash" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "pending", "running", "waiting_for_approval", "waiting_for_event", "waiting_for_retry", "completed", "failed_pending_compensation", "failed_terminal", "cancel_requested", "canceled", "expired", "compensating", "compensated", "compensation_failed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "trigger_kind" }, "type": { "const": "eq" }, "value": { "enum": [ "manual", "event", "schedule", "webhook", "agent_requested", "api" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "input_snapshot" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "request_fingerprint" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "request_fingerprint" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "request_fingerprint" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "request_fingerprint" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "output_snapshot" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_refs_snapshot" }, "type": { "const": "eq" }, "value": { "items": { "properties": { "object_id": { "type": "string" }, "object_type": { "type": "string" } }, "required": [ "object_type", "object_id" ], "type": "object" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "current_step_keys" }, "type": { "const": "eq" }, "value": { "items": { "type": "string" }, "type": "array" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "initiated_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "initiated_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "initiated_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "initiated_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delegated_agent_installation_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delegated_agent_installation_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delegated_agent_installation_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "delegated_agent_installation_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_transition_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_transition_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_transition_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "expires_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "correlation_id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "correlation_id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "correlation_id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "correlation_id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "idempotency_key" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "idempotency_key" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "idempotency_key" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "idempotency_key" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "failure_summary" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "failure_summary" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "compensation_summary" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "compensation_summary" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contestability_ref" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contestability_ref" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contestability_ref" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "contestability_ref" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "definition_id", "run_key", "workflow_key", "workflow_version", "definition_hash", "status", "trigger_kind", "request_fingerprint", "initiated_by", "delegated_agent_installation_id", "started_at", "last_transition_at", "completed_at", "expires_at", "correlation_id", "idempotency_key", "failure_summary", "compensation_summary", "contestability_ref" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_run" }, "properties": { "additionalProperties": false, "properties": { "compensation_summary": { "title": "Bounded compensation outcome", "type": "string" }, "completed_at": { "format": "date-time", "title": "Terminal success / failure / cancellation / compensation terminal", "type": "string" }, "contestability_ref": { "title": "External support / appeal reference for guest-impacting automated decisions", "type": "string" }, "correlation_id": { "title": "Root correlation id for event joins", "type": "string" }, "current_step_keys": { "items": { "type": "string" }, "title": "Active / waiting step keys for fast display", "type": "array" }, "definition_hash": { "title": "Copied from definition at start time. Drift rejects step execution.", "type": "string" }, "definition_id": { "title": "Workflow definition object id. Part of the durable idempotency key.", "type": "string" }, "delegated_agent_installation_id": { "title": "Set when an installed agent initiated the run; mirrors the `workflow_run_started_by_agent_installation` link target", "type": "string" }, "expires_at": { "format": "date-time", "title": "Run timeout", "type": "string" }, "failure_summary": { "title": "Bounded terminal failure summary; full details stay on step runs", "type": "string" }, "id": { "title": "Run id", "type": "string" }, "idempotency_key": { "title": "Key used to start the run", "type": "string" }, "initiated_by": { "title": "`Principal::stable_id()` of caller that started the run", "type": "string" }, "input_snapshot": { "title": "Frozen, redacted start input" }, "last_transition_at": { "format": "date-time", "title": "Updated on every lifecycle transition", "type": "string" }, "output_snapshot": { "title": "Frozen completion output" }, "request_fingerprint": { "title": "SHA-256 over canonical start request fields. Same run_key with a different fingerprint is rejected.", "type": "string" }, "run_key": { "title": "Host-supplied business / dedupe key. Immutable.", "type": "string" }, "started_at": { "format": "date-time", "title": "Wall-clock start", "type": "string" }, "status": { "enum": [ "pending", "running", "waiting_for_approval", "waiting_for_event", "waiting_for_retry", "completed", "failed_pending_compensation", "failed_terminal", "cancel_requested", "canceled", "expired", "compensating", "compensated", "compensation_failed" ], "title": "Lifecycle status", "type": "string" }, "target_refs_snapshot": { "description": "Frozen `{object_type, object_id}` targets requested at start. Convenience snapshot only — graph traversal uses concrete `workflow_run_targets_*` links and never embeds payloads.", "items": { "properties": { "object_id": { "type": "string" }, "object_type": { "type": "string" } }, "required": [ "object_type", "object_id" ], "type": "object" }, "title": "Workflow run target refs snapshot", "type": "array" }, "trigger_kind": { "enum": [ "manual", "event", "schedule", "webhook", "agent_requested", "api" ], "title": "Copied from start request or definition default", "type": "string" }, "workflow_key": { "title": "Copied from definition at start time", "type": "string" }, "workflow_version": { "title": "Copied from definition at start time", "type": "string" } }, "required": [ "id", "definition_id", "run_key", "workflow_key", "workflow_version", "definition_hash", "status", "trigger_kind", "input_snapshot", "request_fingerprint", "current_step_keys", "started_at", "last_transition_at", "correlation_id", "idempotency_key" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.workflow_run:read" ] } ], "summary": "Search Workflow run", "tags": [ "workflows" ] } }, "/v1/object-types/hospitality.workflow_step_run/objects/{id}": { "get": { "description": "Read an existing instance.\n\nOne step's runtime state inside a workflow run. A retry increments `attempt_count`; a new step run row is created only for fan-out branches or subworkflow children. `context_hash` is the canonical JCS+SHA-256 over the proposal §4.4.2 input set; drift supersedes any held approval. The self-reference for compensation is on the `workflow_step_run_compensates_step_run` link, not an inline UUID.", "operationId": "get_hospitality_workflow_step_run", "parameters": [ { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_step_run" }, "properties": { "additionalProperties": false, "properties": { "action_name": { "title": "Copied from definition for action steps", "type": "string" }, "attempt_count": { "title": "Starts at 0; increments before each attempt", "type": "integer" }, "compensation_role": { "enum": [ "original", "compensating_step" ], "title": "Marker for rows participating in a compensation relationship. Self-reference uses `workflow_step_run_compensates_step_run`, not an inline UUID.", "type": "string" }, "completed_at": { "format": "date-time", "title": "Terminal step time", "type": "string" }, "context_hash": { "title": "Canonical JCS+SHA-256 over the §4.4.2 input set", "type": "string" }, "executed_by": { "title": "`Principal::stable_id()` that executed or resolved the step", "type": "string" }, "external_reference": { "title": "PSP, PMS, Slack, Linear, webhook, or job reference", "type": "string" }, "function_name": { "title": "Copied from definition for function steps", "type": "string" }, "id": { "title": "Step run id", "type": "string" }, "idempotency_key": { "title": "Durable key used for mutating action/function/external call", "type": "string" }, "last_error_code": { "title": "Structured failure code", "type": "string" }, "last_error_summary": { "title": "Bounded failure summary", "type": "string" }, "last_result_status": { "enum": [ "succeeded", "failed_retryable", "failed_terminal", "skipped", "waiting_for_event", "waiting_for_retry", "canceled", "expired" ], "title": "Raw result_status last recorded by the runner; failed_retryable normalizes to status waiting_for_retry.", "type": "string" }, "max_attempts": { "title": "From retry policy", "type": "integer" }, "next_attempt_at": { "format": "date-time", "title": "Set while waiting for retry", "type": "string" }, "parameter_snapshot": { "title": "Frozen parameters after template resolution" }, "result_snapshot": { "title": "Frozen, redacted step result" }, "started_at": { "format": "date-time", "title": "First attempt start", "type": "string" }, "status": { "enum": [ "planned", "ready", "running", "waiting_for_approval", "waiting_for_event", "waiting_for_retry", "succeeded", "failed_terminal", "skipped", "cancel_requested", "canceled", "expired", "compensating", "compensated", "compensation_failed" ], "title": "Lifecycle status", "type": "string" }, "step_key": { "title": "Matches the definition step key", "type": "string" }, "step_type": { "enum": [ "action", "function", "approval_gate", "event_wait", "branch", "subworkflow", "external_task" ], "title": "Copied from definition", "type": "string" }, "target_ref": { "description": "`{object_type, object_id}` resolved at runtime", "properties": { "object_id": { "type": "string" }, "object_type": { "type": "string" } }, "required": [ "object_type", "object_id" ], "title": "Workflow step run target ref", "type": "object" } }, "required": [ "id", "step_key", "step_type", "status", "parameter_snapshot", "context_hash", "attempt_count", "max_attempts" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" } } }, "description": "Object found.", "headers": { "ETag": { "description": "Quoted strong validator (RFC 7232 §2.3) carrying the object's monotonic version. Informational on the read path — object mutation goes through typed actions on `/v1/actions/{action}/apply`, not raw CRUD.", "schema": { "pattern": "^\"\\d+\"$", "type": "string" } } } }, "404": { "description": "No object with that id (or soft-deleted)." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.workflow_step_run:read" ] } ], "summary": "Read Workflow step run", "tags": [ "workflows" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.workflow_step_run/objects/{id}/as-of": { "get": { "description": "Time-travel read: the instance as it stood at the `at` watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.\n\nOne step's runtime state inside a workflow run. A retry increments `attempt_count`; a new step run row is created only for fan-out branches or subworkflow children. `context_hash` is the canonical JCS+SHA-256 over the proposal §4.4.2 input set; drift supersedes any held approval. The self-reference for compensation is on the `workflow_step_run_compensates_step_run` link, not an inline UUID.", "operationId": "get_hospitality_workflow_step_run_as_of", "parameters": [ { "description": "The watermark: an event `seq` (integer, canonical — the `/v1/events` cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant's stream).", "in": "query", "name": "at", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "at": { "type": "string" }, "events_applied": { "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "last_event_seq": { "type": "integer" }, "last_event_ts": { "format": "date-time", "type": "string" }, "object_type": { "const": "hospitality.workflow_step_run" }, "properties": { "additionalProperties": true, "description": "Log-shaped folded bag: each entry is a typed `{kind, value}` object, a `{redacted: [markings]}` sentinel, or a `{truncated_bytes: n}` sentinel.", "type": "object" } }, "required": [ "object_type", "id", "at", "last_event_seq", "last_event_ts", "events_applied", "properties" ], "type": "object" } } }, "description": "The reconstructed as-of state." }, "404": { "description": "Object did not exist at the watermark (not yet created, or already deleted)." }, "422": { "description": "Malformed `at`, or the object's history predates structural event images and cannot back a faithful reconstruction." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.workflow_step_run:read" ] } ], "summary": "Read Workflow step run as of a watermark", "tags": [ "workflows" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/object-types/hospitality.workflow_step_run/objects/{id}/links/{link_type}": { "get": { "description": "List the neighbours of an instance along a typed link. Direction is inferred when the source binds the link on exactly one side; symmetric links (same object type on both ends) require an explicit `?direction=out` or `?direction=in`.\n\nOne step's runtime state inside a workflow run. A retry increments `attempt_count`; a new step run row is created only for fan-out branches or subworkflow children. `context_hash` is the canonical JCS+SHA-256 over the proposal §4.4.2 input set; drift supersedes any held approval. The self-reference for compensation is on the `workflow_step_run_compensates_step_run` link, not an inline UUID.", "operationId": "list_links_hospitality_workflow_step_run", "parameters": [ { "description": "Edge direction to follow. Optional when the link binds the source on exactly one side; required for symmetric links.", "in": "query", "name": "direction", "required": false, "schema": { "enum": [ "out", "in" ] } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "in": "query", "name": "as_of", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Read through an open branch's copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422). The branch must exist under the caller's tenant.", "in": "query", "name": "branch", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the typed link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — direction conflicts with the link's binding." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.workflow_step_run:read" ] } ], "summary": "List links of Workflow step run", "tags": [ "workflows" ] }, "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "API name of the link type. Narrowed to link types that bind this source object type on at least one side.", "in": "path", "name": "link_type", "required": true, "schema": { "enum": [ "hospitality.link.approval_gate_for_workflow_step_run", "hospitality.link.workflow_step_run_compensates_step_run", "hospitality.link.workflow_step_run_for_workflow_run", "hospitality.link.workflow_step_run_used_agent_installation" ] } } ] }, "/v1/object-types/hospitality.workflow_step_run/objects/{id}/traverse": { "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "RPC-shaped traversal. Pick the edge by `(link_type, direction)` or by `role` — the registry resolves a role name (e.g. `managed_by`, `direct_reports`) to the underlying link side. `link_type` wins when both are present.\n\nOne step's runtime state inside a workflow run. A retry increments `attempt_count`; a new step run row is created only for fan-out branches or subworkflow children. `context_hash` is the canonical JCS+SHA-256 over the proposal §4.4.2 input set; drift supersedes any held approval. The self-reference for compensation is on the `workflow_step_run_compensates_step_run` link, not an inline UUID.", "operationId": "traverse_hospitality_workflow_step_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Body for `POST .../traverse`. At least one of `link_type` or `role` MUST be supplied — the server returns `422 missing_traversal_target` when both are absent. `link_type` wins when both are set.", "properties": { "as_of": { "description": "RFC3339 temporal window: return neighbours whose edge was in effect at this instant (`[effective_from, effective_to)`) instead of now.", "format": "date-time", "type": "string" }, "branch": { "description": "Traverse through an open branch's overlay view instead of the canonical (main) plane. Does not compose with `as_of` (422).", "format": "uuid", "type": "string" }, "cursor": { "type": "string" }, "direction": { "description": "Edge direction. Optional when the binding is asymmetric.", "enum": [ "out", "in" ] }, "limit": { "maximum": 500, "minimum": 1, "type": "integer" }, "link_type": { "description": "API name of the link type to traverse. Narrowed to link types that bind the source. Wins over `role`.", "enum": [ "hospitality.link.approval_gate_for_workflow_step_run", "hospitality.link.workflow_step_run_compensates_step_run", "hospitality.link.workflow_step_run_for_workflow_run", "hospitality.link.workflow_step_run_used_agent_installation" ] }, "role": { "description": "Link-side role name (e.g. `managed_by`, `direct_reports`). Mutually substitutable with `link_type` — the registry resolves the role to its underlying link and direction.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "type": "object" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "direction": { "enum": [ "out", "in" ] }, "has_more": { "type": "boolean" }, "link_type": { "type": "string" }, "next_cursor": { "type": "string" } }, "required": [ "link_type", "direction", "data", "has_more" ], "type": "object" } } }, "description": "Neighbours along the resolved link." }, "404": { "description": "No object with that id, or link type unknown." }, "422": { "description": "Validation error — must supply `link_type` or `role`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.workflow_step_run:read" ] } ], "summary": "Traverse from Workflow step run", "tags": [ "workflows" ] } }, "/v1/object-types/hospitality.workflow_step_run/search": { "post": { "description": "Search for instances. Filters `eq`, `contains`, `gte` and `lte` AND-compose; `or` / `not` are additive follow-ups. Pages with an opaque `cursor`; the `+1` fetch returns `has_more` without a second round-trip. Ordered by `sort_by` (default `created_at`) in `order` (default ascending), `id` breaking ties; rows with no value for a property key sort last.\n\nOne step's runtime state inside a workflow run. A retry increments `attempt_count`; a new step run row is created only for fan-out branches or subworkflow children. `context_hash` is the canonical JCS+SHA-256 over the proposal §4.4.2 input set; drift supersedes any held approval. The self-reference for compensation is on the `workflow_step_run_compensates_step_run` link, not an inline UUID.", "operationId": "search_hospitality_workflow_step_run", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "branch": { "description": "Optional open-branch id. Search composes that branch's copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.", "format": "uuid", "type": "string" }, "cursor": { "description": "Opaque cursor from a prior response's `next_cursor`. Pass back verbatim; do not introspect.", "type": "string" }, "filters": { "description": "Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by `limit`.", "items": { "oneOf": [ { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "id" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "step_key" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "step_key" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "step_key" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "step_key" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "step_type" }, "type": { "const": "eq" }, "value": { "enum": [ "action", "function", "approval_gate", "event_wait", "branch", "subworkflow", "external_task" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "status" }, "type": { "const": "eq" }, "value": { "enum": [ "planned", "ready", "running", "waiting_for_approval", "waiting_for_event", "waiting_for_retry", "succeeded", "failed_terminal", "skipped", "cancel_requested", "canceled", "expired", "compensating", "compensated", "compensation_failed" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "action_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "action_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "action_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "action_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "function_name" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "function_name" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "function_name" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "function_name" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "target_ref" }, "type": { "const": "eq" }, "value": { "properties": { "object_id": { "type": "string" }, "object_type": { "type": "string" } }, "required": [ "object_type", "object_id" ], "type": "object" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "parameter_snapshot" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "context_hash" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "context_hash" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "context_hash" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "context_hash" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "idempotency_key" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "idempotency_key" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "idempotency_key" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "idempotency_key" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "attempt_count" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "attempt_count" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "attempt_count" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_attempts" }, "type": { "const": "eq" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_attempts" }, "type": { "const": "gte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "max_attempts" }, "type": { "const": "lte" }, "value": { "type": "integer" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_attempt_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_attempt_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "next_attempt_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "started_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "eq" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "gte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "completed_at" }, "type": { "const": "lte" }, "value": { "format": "date-time", "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_error_code" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_error_code" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_error_code" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_error_code" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_error_summary" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_error_summary" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "result_snapshot" }, "type": { "const": "eq" }, "value": {} }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "last_result_status" }, "type": { "const": "eq" }, "value": { "enum": [ "succeeded", "failed_retryable", "failed_terminal", "skipped", "waiting_for_event", "waiting_for_retry", "canceled", "expired" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_reference" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_reference" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_reference" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "external_reference" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "executed_by" }, "type": { "const": "eq" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "executed_by" }, "type": { "const": "contains" }, "value": { "description": "Case-insensitive substring needle.", "minLength": 1, "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "executed_by" }, "type": { "const": "gte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "executed_by" }, "type": { "const": "lte" }, "value": { "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "property": { "const": "compensation_role" }, "type": { "const": "eq" }, "value": { "enum": [ "original", "compensating_step" ], "type": "string" } }, "required": [ "type", "property", "value" ], "type": "object" } ] }, "type": "array" }, "limit": { "description": "Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).", "maximum": 500, "minimum": 1, "type": "integer" }, "order": { "default": "asc", "description": "Direction of `sort_by`: `asc` (oldest / smallest first) or `desc`. A cursor is bound to the `sort_by` and `order` it was minted under; another pair is refused (422).", "enum": [ "asc", "desc" ], "type": "string" }, "property_id": { "description": "The house a desk stands in: keeps this property's rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house's — the meaning `property_id` has on the event tail.", "format": "uuid", "type": "string" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "sort_by": { "default": "created_at", "description": "What the page is ordered by: the row's `created_at` or `updated_at`, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).", "enum": [ "created_at", "updated_at", "id", "step_key", "step_type", "status", "action_name", "function_name", "context_hash", "idempotency_key", "attempt_count", "max_attempts", "next_attempt_at", "started_at", "completed_at", "last_error_code", "last_error_summary", "last_result_status", "external_reference", "executed_by", "compensation_role" ], "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "object_type": { "const": "hospitality.workflow_step_run" }, "properties": { "additionalProperties": false, "properties": { "action_name": { "title": "Copied from definition for action steps", "type": "string" }, "attempt_count": { "title": "Starts at 0; increments before each attempt", "type": "integer" }, "compensation_role": { "enum": [ "original", "compensating_step" ], "title": "Marker for rows participating in a compensation relationship. Self-reference uses `workflow_step_run_compensates_step_run`, not an inline UUID.", "type": "string" }, "completed_at": { "format": "date-time", "title": "Terminal step time", "type": "string" }, "context_hash": { "title": "Canonical JCS+SHA-256 over the §4.4.2 input set", "type": "string" }, "executed_by": { "title": "`Principal::stable_id()` that executed or resolved the step", "type": "string" }, "external_reference": { "title": "PSP, PMS, Slack, Linear, webhook, or job reference", "type": "string" }, "function_name": { "title": "Copied from definition for function steps", "type": "string" }, "id": { "title": "Step run id", "type": "string" }, "idempotency_key": { "title": "Durable key used for mutating action/function/external call", "type": "string" }, "last_error_code": { "title": "Structured failure code", "type": "string" }, "last_error_summary": { "title": "Bounded failure summary", "type": "string" }, "last_result_status": { "enum": [ "succeeded", "failed_retryable", "failed_terminal", "skipped", "waiting_for_event", "waiting_for_retry", "canceled", "expired" ], "title": "Raw result_status last recorded by the runner; failed_retryable normalizes to status waiting_for_retry.", "type": "string" }, "max_attempts": { "title": "From retry policy", "type": "integer" }, "next_attempt_at": { "format": "date-time", "title": "Set while waiting for retry", "type": "string" }, "parameter_snapshot": { "title": "Frozen parameters after template resolution" }, "result_snapshot": { "title": "Frozen, redacted step result" }, "started_at": { "format": "date-time", "title": "First attempt start", "type": "string" }, "status": { "enum": [ "planned", "ready", "running", "waiting_for_approval", "waiting_for_event", "waiting_for_retry", "succeeded", "failed_terminal", "skipped", "cancel_requested", "canceled", "expired", "compensating", "compensated", "compensation_failed" ], "title": "Lifecycle status", "type": "string" }, "step_key": { "title": "Matches the definition step key", "type": "string" }, "step_type": { "enum": [ "action", "function", "approval_gate", "event_wait", "branch", "subworkflow", "external_task" ], "title": "Copied from definition", "type": "string" }, "target_ref": { "description": "`{object_type, object_id}` resolved at runtime", "properties": { "object_id": { "type": "string" }, "object_type": { "type": "string" } }, "required": [ "object_type", "object_id" ], "title": "Workflow step run target ref", "type": "object" } }, "required": [ "id", "step_key", "step_type", "status", "parameter_snapshot", "context_hash", "attempt_count", "max_attempts" ], "type": "object" }, "provenance": { "$ref": "#/components/schemas/ProvenanceEnvelope" }, "scope": { "$ref": "#/components/schemas/OrgScope" }, "tenant_id": { "format": "uuid", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "object_type", "id", "tenant_id", "scope", "properties", "version", "created_at", "updated_at" ], "type": "object" }, "type": "array" }, "has_more": { "type": "boolean" }, "next_cursor": { "description": "Cursor for the next page; omitted when the result set is exhausted.", "type": "string" } }, "required": [ "data", "has_more" ], "type": "object" } } }, "description": "Search results, ordered by (`sort_by`, id) in the requested `order` (ascending by default)." }, "422": { "description": "Validation error — unknown property or filter type mismatch." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] }, { "aerandil_oauth": [ "objects:hospitality.workflow_step_run:read" ] } ], "summary": "Search Workflow step run", "tags": [ "workflows" ] } }, "/v1/object-types/{api_name}": { "get": { "description": "Schema-discovery detail — returns the summary fields plus the full property list, each property carrying its typed [`DataTypeSummary`]. SDKs can render forms or run client-side validation from the response without parsing the OpenAPI document.", "operationId": "get_object_type", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectTypeDetail" } } }, "description": "Object type detail including every declared property." }, "404": { "description": "No object type with that api_name." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Get object type detail", "tags": [ "metadata" ] }, "parameters": [ { "description": "API name of the object type (e.g. `hospitality.reservation`).", "in": "path", "name": "api_name", "required": true, "schema": { "type": "string" } } ] }, "/v1/onboarding-links/{token}": { "get": { "description": "Public — the hotel holds no bearer of ours. The link the operator sends the hotel, and where Stripe's hosted onboarding sends it when its own link has expired, been opened before, or been spent by a messaging client's preview. Answers a small self-contained HTML page — the house's name and one button, \"Continue to Stripe\", a form that POSTs to this same address — and spends nothing: a mail scanner or a link preview that fetches the link leaves it as it was. No script, no external asset (`Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline'`), `Referrer-Policy: no-referrer`. Every refusal — forged, expired, used, replaced, a closed account — is the same `404`, which says nothing about whether the account exists, and Stripe is asked nothing. Rate-limited per IP like `/oauth/token`.", "operationId": "show_onboarding_link", "parameters": [ { "description": "The signed one-use token the operator's onboarding link minted.", "in": "path", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "text/html": { "schema": { "type": "string" } } }, "description": "The page with the one button.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`onboarding_link_not_found` — expired, used, replaced or never ours." }, "429": { "description": "Per-IP rate limit exceeded (the `/oauth/token` limiter)." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No card rail, or no public address, on this deployment." } }, "security": [], "summary": "The hotel's onboarding link: a page that continues to Stripe", "tags": [ "finance" ] }, "post": { "description": "Public — the page's button. A fresh Account Link with the original's parameters, and a `303` to it. The token is the credential — signed by the deployment, good for seven days, and good once: this use mints the next link (carried in the fresh Stripe link's own refresh address) and retires this one, and a new link from the operator retires it too. Every refusal is the same `404`. Rate-limited per IP like `/oauth/token`.", "operationId": "refresh_onboarding_link", "parameters": [ { "description": "The signed one-use token the operator's onboarding link minted.", "in": "path", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "303": { "description": "To Stripe's fresh onboarding form.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" }, "Location": { "schema": { "format": "uri", "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`onboarding_link_not_found` — expired, used, replaced or never ours." }, "429": { "description": "Per-IP rate limit exceeded (the `/oauth/token` limiter)." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No card rail, or no public address, on this deployment." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Stripe could not be reached; the link is not spent — try it again." } }, "security": [], "summary": "Continue to Stripe: a fresh onboarding form", "tags": [ "finance" ] } }, "/v1/openapi.json": { "get": { "description": "The machine-readable contract for this API. JSON Schema 2020-12 dialect throughout. Public — the document is metadata, not protected data.", "operationId": "aerandil_openapi_json", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OpenAPI 3.1 document." } }, "security": [], "summary": "OpenAPI 3.1 document", "tags": [ "system" ] } }, "/v1/participant-dispatches/{id}/ack": { "parameters": [ { "description": "The `participant_dispatch_attempt` row id — same id the coordinator stamped into the CloudEvents `subject` and into the outbound dispatch envelope.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "Participant → coordinator. Confirms receipt of a dispatch envelope. Optional in v1 for HTTPS POST profiles (the original POST's `2xx` response is the implicit ack); REQUIRED for `agent_installation` SSE dispatches because the SSE channel is asymmetric. \n\n**Envelope shape.** A signed CloudEvents 1.0 envelope with `type = aerandil.participant_dispatch.acknowledged`. Ed25519 detached signature over the canonical bytes (RFC 8785 JSON Canonicalization); kid resolves against the participation row's `runner_signing_key_ref`. \n\n**Idempotency.** The dispatch row carries the acknowledged-at timestamp; a second ack against an already-acknowledged row returns the same `200` without state change. \n\n**Auth.** Requires the deployment-owned service principal with the `internal:participant_dispatch:receive` scope (not a tenant token).", "operationId": "ack_participant_dispatch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParticipantDispatchAckEnvelope" } } }, "description": "Signed `dispatch_ack` envelope (proposal 0022 §7.2).", "required": true }, "responses": { "200": { "description": "Ack accepted (or idempotent replay against an already-acknowledged row)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid bearer credential." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Principal lacks `internal:participant_dispatch:receive` scope, or is not a service principal." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No dispatch row with that id (or row is in a different tenant)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Illegal status transition — the row is in a terminal state and cannot be re-acknowledged." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Envelope parse / signature verification failed (malformed JSON, wrong `type`, expired `time`, signature mismatch)." } }, "summary": "Acknowledge receipt of a dispatch", "tags": [ "participant-dispatch" ] } }, "/v1/participant-dispatches/{id}/results": { "parameters": [ { "description": "The `participant_dispatch_attempt` row id — same id the coordinator stamped into the CloudEvents `subject` and into the outbound dispatch envelope.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "Participant → coordinator. Submits the terminal result of a dispatch. Maps 1:1 onto a `record_federated_contribution` action for federated mode, or `record_workflow_step_result` for workflow mode — both downstream actions enforce their own idempotency on the contribution / step fingerprint, so a re-delivered envelope with the same payload is a benign replay. \n\n**Envelope shape.** A signed CloudEvents 1.0 envelope with `type = aerandil.participant_dispatch.result_submitted`. Same signature rules as the ack route. \n\n**Idempotency conflict.** A re-delivered envelope with the same idempotency key but a *different* payload hash is rejected with `409` and the receiver emits an `aerandil.participant_dispatch.delivery_failed` event with `failure_reason = idempotency_conflict`. \n\n**Auth.** Same service principal + scope as the ack route.", "operationId": "submit_participant_dispatch_result", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParticipantDispatchResultEnvelope" } } }, "description": "Signed `result_submit` envelope (proposal 0022 §7.3).", "required": true }, "responses": { "200": { "description": "Result recorded (or idempotent replay against an already-recorded row)." }, "401": { "$ref": "#/paths/~1v1~1participant-dispatches~1%7Bid%7D~1ack/post/responses/401" }, "403": { "$ref": "#/paths/~1v1~1participant-dispatches~1%7Bid%7D~1ack/post/responses/403" }, "404": { "$ref": "#/paths/~1v1~1participant-dispatches~1%7Bid%7D~1ack/post/responses/404" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Illegal status transition, OR idempotency conflict (same key, different payload)." }, "422": { "$ref": "#/paths/~1v1~1participant-dispatches~1%7Bid%7D~1ack/post/responses/422" } }, "summary": "Submit a terminal dispatch result", "tags": [ "participant-dispatch" ] } }, "/v1/payment-cards/{card_id}/retirement": { "post": { "description": "Detaches the card at the processor, then retires it on the ledger as `removed` — the guest asked, or the desk withdrew it. Detachment is permanent at Stripe, so the ledger's refusals (already retired, held by another rail) run first, and a retry after a crash between the two halves finds the card already detached and simply records the retirement. Never a deletion: the row keeps naming the instrument behind any settled payment, and the retention clock decides when it goes. Cards that merely aged out are swept by the night audit (`retire_expired_cards`) without a processor call.", "operationId": "retire_card", "parameters": [ { "description": "The card on file to forget.", "in": "path", "name": "card_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetireCardResponse" } } }, "description": "Detached and retired.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`payment_card_not_active` — already retired; `card_not_on_this_rail` — held by a processor other than the configured one." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No card rail is configured on this deployment." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`rail_unavailable` — the card processor could not be reached (a transport failure, a 5xx, a 429, or this request's key still running at the processor). The card is still on file at both ends. Try again after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait before trying the same request again (RFC 9110 §10.2.3) — the queue's first backoff.", "schema": { "minimum": 0, "type": "integer" } } } } }, "summary": "Forget a card on file", "tags": [ "finance" ] } }, "/v1/payment-disputes/{dispute_id}/evidence/submission": { "post": { "description": "The house counters the chargeback with the evidence packet the kernel assembled (`assemble_dispute_evidence`). Refused before anything is asked of the processor when the issuer is not waiting on the house, the deadline has passed, the evidence already went (here or at the processor's dashboard), the packet named is not the case's current one, the processor refused this packet before, a source the packet pinned has changed since it was assembled, or the packet has gaps the request does not acknowledge (`submit_with_gaps: true`, recorded on the packet with who submitted). Then each document is rendered — the folio's issued invoice as the document the guest was handed, otherwise a PDF statement of the pinned object — uploaded to Stripe (`purpose=dispute_evidence`, at most 4.5 MB in all), and the dispute updated with the packet's text fields and the files, submitted. **A processor's refusal is an outcome, not an error**: `200` with `outcome: refused` and Stripe's words, recorded on the case; the retry is a new packet. A failure Stripe saved under the packet's key is read back off the dispute: Stripe holding the packet's files is the submission, holding nothing of it is the refusal (`refusal.code: processor_saved_failure`, assemble again). The packet is marked `sending` with its file ids before the dispute update goes, so a retry after a lost answer (a `503`, a dropped connection) finishes that packet — the same files under the same key, Stripe's saved answer recorded — even after Stripe's webhook has counted the submission. Every processor call is keyed from the packet's own id. W1 (2026-10-21): a packet with a Visa Compelling Evidence 3.0 section sends it as Stripe's nested `evidence[enhanced_evidence][visa_compelling_evidence_3][…]` keys (the booking's half and two prior charges, each prior's payment checked against the version it was read at), the signed registration card, the guest's messages and the key-card taps go as files of their own, and the documents' pages are counted against the card's network before anything is uploaded. An inquiry the issuer escalated to a chargeback takes this submission once more (one per phase). Move 12 (2026-10-22): the submission certifies the dispute-fee waiver from facts the kernel holds and stamps it on the case (`waiver`: covered or not, and the first condition missed) — a whole packet on time, a reason the packet defends (`fraudulent`, `unrecognized`, `credit_not_processed`, `product_not_received`, `duplicate`), a card not keyed by hand, Radar's `normal` (Stripe's own word on the disputed charge, read at every submission) with no elevated rating set aside, the account's chargebacks under 0.5% of its charges over the rolling year (weighed once the year holds 1,000 charges), and room under its cap (25% of the year's platform fees) for the case's own two fees, or fewer than five cases taken; a covered case that is lost passes neither fee to the hotel. Move 13: a gap-free packet still unsent 48 hours before the deadline is submitted by the night audit through the same path, as `system`. `501` unless `AERANDIL_STRIPE_ENABLED=1`.", "operationId": "submit_dispute_evidence", "parameters": [ { "description": "The chargeback (`payment_dispute`) to counter.", "in": "path", "name": "dispute_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "packet_id": { "description": "The packet the desk reviewed; refused when another assembly has replaced it.", "format": "uuid", "type": "string" }, "submit_with_gaps": { "default": false, "description": "Submit knowing the packet's gaps; required when it has any.", "type": "boolean" } }, "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "dispute_evidence_packet_id": { "format": "uuid", "type": "string" }, "file_count": { "type": "integer" }, "idempotent_replay": { "type": "boolean" }, "outcome": { "enum": [ "submitted", "refused" ], "type": "string" }, "packet_version": { "type": [ "integer", "null" ] }, "past_due": { "type": [ "boolean", "null" ] }, "payment_dispute_id": { "format": "uuid", "type": "string" }, "refusal": { "properties": { "code": { "type": [ "string", "null" ] }, "message": { "type": "string" } }, "type": [ "object", "null" ] }, "submission_count": { "type": [ "integer", "null" ] }, "submitted_at": { "format": "date-time", "type": [ "string", "null" ] }, "waiver": { "description": "Move 12 (2026-10-22): the dispute-fee waiver, certified at this submission and stamped on the case — if the case is lost, neither of the network's fees is passed to the hotel. `null` when the processor refused the packet.", "properties": { "cap_case_floor": { "type": [ "integer", "null" ] }, "cap_cases": { "type": [ "integer", "null" ] }, "cap_limit": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "cap_used": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "certified": { "type": "boolean" }, "chargebacks_in_year": { "type": [ "integer", "null" ] }, "charges_in_year": { "type": [ "integer", "null" ] }, "condition": { "description": "The first condition not met (`WAIVER_REFUSALS`).", "enum": [ "evidence_gaps", "submitted_late", "reason_not_defended", "hand_keyed", "card_unknown", "radar_not_normal", "radar_unknown", "radar_unread", "elevated_rating_overridden", "no_merchant_account", "dispute_ratio", "cap_exhausted", null ], "type": [ "string", "null" ] }, "decided_at": { "format": "date-time", "type": "string" }, "pledged": { "description": "What a covered case holds of the cap while it is open: its two fees as priced at certification. `null` when not covered.", "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "radar_risk_level": { "description": "Stripe Radar's rating of the payment at authorisation, verbatim (`outcome.risk_level` on the disputed intent's latest charge, read at certification; never the kernel's own assessment).", "type": [ "string", "null" ] }, "ratio_charge_floor": { "description": "The charges the year must hold before the ratio is weighed (1,000); under it `dispute_ratio` is never the condition.", "type": [ "integer", "null" ] }, "refusal": { "description": "The same, in words.", "type": [ "string", "null" ] } }, "required": [ "certified", "decided_at" ], "type": [ "object", "null" ] } }, "required": [ "payment_dispute_id", "dispute_evidence_packet_id", "outcome" ], "type": "object" } } }, "description": "The processor was asked and its answer recorded: the evidence submitted, or the processor's refusal.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`evidence_already_submitted`, `dispute_not_awaiting_evidence`, `evidence_deadline_passed`, `no_evidence_packet`, `evidence_packet_superseded`, `evidence_packet_refused`, `evidence_packet_stale` (assemble again), `evidence_gaps_unacknowledged` (its `parameters.gaps` lists them), `dispute_not_on_the_rail` (the case carries no processor reference), `evidence_submission_unconfirmed` (Stripe failed the update and the dispute could not be read back; the packet stays on its way), `evidence_too_many_pages` (W1: the documents render to more pages than the card's network takes — fewer than 50 in all, 19 for Mastercard or a card whose network is not known; `parameters` carries `page_count`, `page_limit`, `card_brand` and each document's pages; nothing reached the processor), or `idempotency_in_flight` (an earlier request under the same `Idempotency-Key` is still running)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`invalid_body`, `evidence_too_large` (the documents come to more than Stripe takes), or `idempotency_key_mismatch` (the `Idempotency-Key` was used for another request)." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No card rail is configured on this deployment." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`rail_unavailable` — Stripe could not be reached (a transport failure, a first-time 5xx, a 429) or still holds the packet's key in flight. Nothing is lost: the packet is on its way, and the same request again finishes it under the same keys.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying the same request (RFC 9110 §10.2.3).", "schema": { "minimum": 0, "type": "integer" } } } } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_dispute_evidence_submission:apply" ] } ], "summary": "Submit a chargeback's evidence packet to the issuer", "tags": [ "finance" ] } }, "/v1/payment-disputes/{dispute_id}/fee-review": { "post": { "description": "A lost chargeback's dispute fee, retried at the night audit, is parked `dispute_fee_recovery = needs_review` when the retry's debit could not be read back from Stripe — never retried blind. This records what a person found: `recovered` (the debit is there; `reference` names Stripe's `py_…`), or `written_off` (it is not; the platform carries the fee, `note` says why). Nothing is owed after either, no retry opens, and the case keeps who settled it and when. Stripe is asked nothing. A case not parked for review, an unknown outcome, or a write-off without a note is a `422`; the same settlement again changes nothing, a different one after it is a `422`. Accepts `Idempotency-Key`. Operator only (`tenant_admin:write`).", "operationId": "settle_dispute_fee_review", "parameters": [ { "description": "The chargeback case (`payment_dispute`).", "in": "path", "name": "dispute_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "note": { "description": "What was found; required for a write-off.", "type": "string" }, "outcome": { "enum": [ "recovered", "written_off" ], "type": "string" }, "reference": { "description": "The Stripe debit (`py_…`) found, when recovered.", "type": "string" } }, "required": [ "outcome" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "dispute_fee_recovered": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "dispute_fee_recovery": { "type": [ "string", "null" ] }, "dispute_fee_reviewed_at": { "format": "date-time", "type": [ "string", "null" ] }, "dispute_fee_written_off": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "idempotent_replay": { "type": "boolean" }, "payment_dispute_id": { "format": "uuid", "type": "string" }, "version": { "type": "integer" } }, "required": [ "payment_dispute_id", "version" ], "type": "object" } } }, "description": "The case as settled.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`idempotency_in_flight` (an earlier request under the same `Idempotency-Key` is still running)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`invalid_body`, the verb's refusal (`invalid_action`: the case is not parked for review, a write-off has no note, or it was settled differently already), or `idempotency_key_mismatch`." } }, "security": [ { "aerandil_oauth": [ "tenant_admin:write" ] } ], "summary": "Settle a dispute fee parked for review", "tags": [ "finance" ] } }, "/v1/payment-disputes/{dispute_id}/late-win/settlement": { "post": { "description": "When a chargeback lost and then won late leaves the case `hotel_reinstatement = pending_operator` — Stripe refused the card rail's transfer back to the hotel (\"If your platform has an insufficient balance, the transfer fails\"; a cross-border corridor Stripe does not allow), or the dispute fee's outcome was unknown — the rail never asks again and the money moves by hand. This records what the operator did: `transferred_by_hand` (they paid the hotel exactly what the case owed, `reference` naming the Stripe transfer `tr_…` or payout `po_…` they made, if any) or `written_off` (`amount`, from nothing up to what was owed, went back; the rest is not owed, for the reason in `note`). The case becomes `settled_by_operator`, keeps the processor's refusal beside the settlement, and the card rail cannot write over it. Stripe is asked nothing. A case not left for the operator, an amount that is not what it owed, another currency, or a write-off without a note is a `422`; the same settlement again changes nothing, a different one after it is a `422`. Accepts `Idempotency-Key`. Operator only (`tenant_admin:write`).", "operationId": "settle_late_win_by_hand", "parameters": [ { "description": "The chargeback case (`payment_dispute`).", "in": "path", "name": "dispute_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "amount": { "$ref": "#/components/schemas/Money" }, "note": { "description": "How it was settled; required for a write-off.", "type": "string" }, "outcome": { "enum": [ "transferred_by_hand", "written_off" ], "type": "string" }, "reference": { "description": "The Stripe transfer (`tr_…`) or payout (`po_…`) that paid the hotel.", "type": "string" } }, "required": [ "outcome", "amount" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "amount": { "$ref": "#/components/schemas/Money" }, "hotel_reinstatement": { "type": "string" }, "idempotent_replay": { "type": "boolean" }, "payment_dispute_id": { "format": "uuid", "type": "string" }, "settled_at": { "format": "date-time", "type": "string" }, "settled_by": { "type": "string" }, "settlement": { "type": "string" }, "version": { "type": "integer" }, "written_off": { "$ref": "#/components/schemas/Money" } }, "type": "object" } } }, "description": "The case as settled.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Another request with this `Idempotency-Key` is still running; retry shortly." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not a case left for the operator, or not what it owed." } }, "security": [ { "aerandil_oauth": [ "tenant_admin:write" ] } ], "summary": "Record a late chargeback win settled by hand", "tags": [ "finance" ] } }, "/v1/payment-requests/{request_id}/pay-link": { "post": { "description": "The page a guest pays a payment request on — a Stripe Payment Link for the request's amount, limited to one completed payment, holding instead of charging for a `preauthorization`. The rail's worker mints it after `request_payment` commits; this route mints it on demand when the worker has not (or could not), and returns a page already recorded as it is, so it is safe to repeat. The guest's payment completes the request through the webhook; cancelling or expiring the request switches the page off. Gated on `request_payment`'s apply scope — whoever may ask the guest for money may mint the page they pay on; the verbs that record the page and its payment are the rail's own and have no public apply. `501` unless `AERANDIL_STRIPE_ENABLED=1`.", "operationId": "payment_request_pay_link", "parameters": [ { "description": "The pending payment request.", "in": "path", "name": "request_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "pay_url": { "format": "uri", "type": "string" }, "payment_request_id": { "format": "uuid", "type": "string" } }, "required": [ "payment_request_id", "pay_url" ], "type": "object" } } }, "description": "The page the guest pays on.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`merchant_account_not_ready` — the property's card payments settle to its own merchant account, which Stripe has not yet let take charges." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`payment_request_not_pending` — the request was completed, cancelled or has expired; it has no page to pay on." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No card rail is configured on this deployment." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`rail_unavailable` — the card processor could not be reached (a transport failure, a 5xx, a 429, or this request's key still running at the processor). No page was minted. Try again after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait before trying the same request again (RFC 9110 §10.2.3) — the queue's first backoff.", "schema": { "minimum": 0, "type": "integer" } } } } }, "summary": "Mint a payment request's hosted pay page", "tags": [ "finance" ] } }, "/v1/payments/rail/health": { "get": { "description": "The card rail's reading — asks the processor nothing: `rail` is `up` (the last request was answered), `down` (it was not, since `down_since`: a transport failure, a 5xx or a 429 — `failure` says which kind, as this kernel last heard it) or `unknown` (nothing asked yet). Since 2026-10-21 `rail`, `down_since`, `since` and `seen_by` are every replica's shared reading — each kernel publishes the transitions it hears — so two replicas answer the same banner; `last_success_at`, `last_failure_at` and `failure` stay this kernel's own. A `401` (the platform's key refused) moves the reading neither up nor down. With the open queue at the house (`property_id`, else the desk's own house, else the tenant): the instructions still to be taken when the rail is back (`queued`, by kind, the oldest's time) and those given up on in the last week (`abandoned`). Counts are cached for a few seconds. `501` unless `AERANDIL_STRIPE_ENABLED=1`.", "operationId": "rail_health", "parameters": [ { "description": "The house whose queue is counted.", "in": "query", "name": "property_id", "required": false, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "abandoned": { "type": "integer" }, "down_since": { "format": "date-time", "type": [ "string", "null" ] }, "failure": { "enum": [ "unreachable", "timeout", "server_error", "rate_limited", null ], "type": [ "string", "null" ] }, "last_failure_at": { "format": "date-time", "type": [ "string", "null" ] }, "last_success_at": { "format": "date-time", "type": [ "string", "null" ] }, "more": { "type": "boolean" }, "oldest_queued_at": { "format": "date-time", "type": [ "string", "null" ] }, "property_id": { "format": "uuid", "type": [ "string", "null" ] }, "queued": { "type": "integer" }, "queued_by_kind": { "properties": { "capture": { "type": "integer" }, "charge_off_session": { "type": "integer" }, "refund": { "type": "integer" }, "top_up": { "type": "integer" }, "void": { "type": "integer" } }, "type": "object" }, "rail": { "enum": [ "up", "down", "unknown" ], "type": "string" }, "seen_by": { "type": [ "string", "null" ] }, "since": { "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "rail", "queued", "abandoned" ], "type": "object" } } }, "description": "The rail's health and the open queue.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No card rail is configured on this deployment." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Whether the card rail can be reached, and what is queued for it", "tags": [ "finance" ] } }, "/v1/payments/{payment_id}/capture": { "post": { "description": "Captures an authorisation at check-out. The amount taken is the folio's truth, which is not always the amount held — a guest who spent less is captured for less, and `amount_received_minor` is what actually moved. No request body: the sum is derived, not asserted by the caller.", "operationId": "capture_card_payment", "parameters": [ { "description": "The authorised payment leg to capture.", "in": "path", "name": "payment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardCaptureResponse" } } }, "description": "Captured.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "202": { "content": { "application/json": { "schema": { "properties": { "already_queued": { "type": "boolean" }, "amount": { "format": "decimal", "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "idempotent_replay": { "type": "boolean" }, "kind": { "enum": [ "capture", "void", "refund", "charge_off_session", "top_up" ], "type": "string" }, "message": { "type": "string" }, "payment_id": { "format": "uuid", "type": [ "string", "null" ] }, "queued": { "const": true, "type": "boolean" }, "rail_instruction_id": { "format": "uuid", "type": "string" }, "state": { "enum": [ "queued", "sending" ], "type": "string" }, "stay_id": { "format": "uuid", "type": [ "string", "null" ] } }, "required": [ "queued", "rail_instruction_id", "kind", "state" ], "type": "object" } } }, "description": "Stripe could not be reached (a transport failure, a 5xx, a 429, or this attempt's key still running at Stripe), so the work was written down as a rail instruction and is taken when the rail is back — under the same processor key as this attempt, so it is never taken twice. A second request while it is queued answers the same instruction (`already_queued`); the desk may cancel it while it is still queued (`cancel_rail_instruction`).", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`rail_instruction_open` — another verb is already queued for this hold or stay (a release behind a queued capture); it is taken first, when the card rail is back." }, "422": { "$ref": "#/components/responses/Unprocessable" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No card rail is configured on this deployment." } }, "summary": "Take the money a hold reserved", "tags": [ "finance" ] } }, "/v1/payments/{payment_id}/refunds": { "post": { "description": "Creates a **new negative-amount payment leg** — proposal 0019's shape, which is why this is `201` and returns a second payment id rather than mutating the original. Partial refunds are ordinary; the kernel computes the remaining refundable balance from the legs already recorded, so the caller does not have to track it. The leg is `pending` until the processor confirms it on the webhook.", "operationId": "refund_card_payment", "parameters": [ { "description": "The captured payment being refunded.", "in": "path", "name": "payment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardRefundRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardRefundResponse" } } }, "description": "The refund leg was recorded.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "202": { "content": { "application/json": { "schema": { "properties": { "already_queued": { "type": "boolean" }, "amount": { "format": "decimal", "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "idempotent_replay": { "type": "boolean" }, "kind": { "enum": [ "capture", "void", "refund", "charge_off_session", "top_up" ], "type": "string" }, "message": { "type": "string" }, "payment_id": { "format": "uuid", "type": [ "string", "null" ] }, "queued": { "const": true, "type": "boolean" }, "rail_instruction_id": { "format": "uuid", "type": "string" }, "state": { "enum": [ "queued", "sending" ], "type": "string" }, "stay_id": { "format": "uuid", "type": [ "string", "null" ] } }, "required": [ "queued", "rail_instruction_id", "kind", "state" ], "type": "object" } } }, "description": "Stripe could not be reached (a transport failure, a 5xx, a 429, or this attempt's key still running at Stripe), so the work was written down as a rail instruction and is taken when the rail is back — under the same processor key as this attempt, so it is never taken twice. A second request while it is queued answers the same instruction (`already_queued`); the desk may cancel it while it is still queued (`cancel_rail_instruction`).", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`rail_instruction_open` — another verb is already queued for this hold or stay (a release behind a queued capture); it is taken first, when the card rail is back." }, "422": { "$ref": "#/components/responses/Unprocessable" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No card rail is configured on this deployment." } }, "summary": "Give money back", "tags": [ "finance" ] } }, "/v1/payments/{payment_id}/void": { "post": { "description": "Cancels an uncaptured authorisation. `void_reason` stays the kernel's word: the hospitality reasons have no processor equivalent, so they travel to the PSP as `abandoned` and survive in full on the row.", "operationId": "void_card_payment", "parameters": [ { "description": "The authorised payment leg to release.", "in": "path", "name": "payment_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardVoidRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardVoidResponse" } } }, "description": "Released.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "202": { "content": { "application/json": { "schema": { "properties": { "already_queued": { "type": "boolean" }, "amount": { "format": "decimal", "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "idempotent_replay": { "type": "boolean" }, "kind": { "enum": [ "capture", "void", "refund", "charge_off_session", "top_up" ], "type": "string" }, "message": { "type": "string" }, "payment_id": { "format": "uuid", "type": [ "string", "null" ] }, "queued": { "const": true, "type": "boolean" }, "rail_instruction_id": { "format": "uuid", "type": "string" }, "state": { "enum": [ "queued", "sending" ], "type": "string" }, "stay_id": { "format": "uuid", "type": [ "string", "null" ] } }, "required": [ "queued", "rail_instruction_id", "kind", "state" ], "type": "object" } } }, "description": "Stripe could not be reached (a transport failure, a 5xx, a 429, or this attempt's key still running at Stripe), so the work was written down as a rail instruction and is taken when the rail is back — under the same processor key as this attempt, so it is never taken twice. A second request while it is queued answers the same instruction (`already_queued`); the desk may cancel it while it is still queued (`cancel_rail_instruction`).", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`rail_instruction_open` — another verb is already queued for this hold or stay (a release behind a queued capture); it is taken first, when the card rail is back." }, "422": { "$ref": "#/components/responses/Unprocessable" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No card rail is configured on this deployment." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.void_authorisation:apply" ] } ], "summary": "Release a hold without taking it", "tags": [ "finance" ] } }, "/v1/persons/{person_id}/payment-cards": { "post": { "description": "Takes the SetupIntent id — never the card's details — and reads the brand, last four, expiry, funding and wallet back off the processor, because a page that collected the card could otherwise claim any brand and last four it liked. What the caller *does* supply is the pair of facts the processor cannot know: how the card was captured (Stripe cannot tell a guest typing on their own phone from an agent typing at the counter, and the difference decides chargeback liability) and how long this jurisdiction says it may be kept.", "operationId": "store_card_for_person", "parameters": [ { "description": "The guest the card binds to.", "in": "path", "name": "person_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCardRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCardResponse" } } }, "description": "The card is on file. The response carries the display triple and nothing else — the token is `payment.token`-marked and this route is not the way around that.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`card_not_collected` — the intent has saved no card yet, because the guest has not completed the form; `invalid_setup_intent_id` — the id is not shaped `seti_` plus letters and digits, refused before the processor is asked; `setup_intent_mismatch` — the processor answered with another intent." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No card rail is configured on this deployment." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`rail_unavailable` — the card processor could not be reached (a transport failure, a 5xx, a 429, or this request's key still running at the processor). The card was not stored. Try again after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait before trying the same request again (RFC 9110 §10.2.3) — the queue's first backoff.", "schema": { "minimum": 0, "type": "integer" } } } } }, "summary": "Record the card a completed SetupIntent saved", "tags": [ "finance" ] } }, "/v1/platform-earnings": { "get": { "description": "A fold over every line the platform-ledger worker read off the platform's own Stripe balance in a UTC calendar month, across every tenant: `hotels` — every merchant account's lines, the per-account month (`/v1/merchant-accounts/{id}/platform-earnings`) summed; `platform` — the lines no hotel owns, recorded at the operator's own tenant (`AERANDIL_PLATFORM_TENANT_ID`): its payouts, Stripe's fees on the platform and the tax on them, reserves, and what no merchant account holds (`unattributed`); `net` — every line, the balance's change. `ties_to_stripe` is the arithmetic of Stripe's Balance summary report run in UTC — Activity (every category bar the payouts: count, gross, fee, net), Total payouts, and their sum — and `by_category` its balance-change-from-activity summary, so the operator ties the month to Stripe to the penny. `unplaced_count` is what was read while no operator tenant was configured: counted, never recorded, so a month carrying any will not tie. The platform operator's read (`tenant_admin:write`).", "operationId": "platform_earnings", "parameters": [ { "description": "The UTC calendar month, `YYYY-MM`.", "in": "query", "name": "month", "required": true, "schema": { "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "account_count": { "type": "integer" }, "from": { "format": "date", "type": "string" }, "line_count": { "type": "integer" }, "month": { "type": "string" }, "platform_tenant_id": { "format": "uuid", "type": [ "string", "null" ] }, "timezone": { "type": "string" }, "to": { "format": "date", "type": "string" }, "totals": { "items": { "properties": { "by_category": { "items": { "properties": { "count": { "type": "integer" }, "fee": { "format": "decimal", "type": "string" }, "gross": { "format": "decimal", "type": "string" }, "net": { "format": "decimal", "type": "string" }, "reporting_category": { "type": "string" } }, "type": "object" }, "type": "array" }, "currency": { "type": "string" }, "hotels": { "description": "Every hotel's lines: the per-account month summed.", "properties": { "account_count": { "type": "integer" }, "dispute_costs": { "properties": { "amounts_recovered": { "format": "decimal", "type": "string" }, "amounts_withdrawn": { "format": "decimal", "type": "string" }, "carried": { "format": "decimal", "type": "string" }, "fees_charged": { "format": "decimal", "type": "string" }, "fees_recovered": { "format": "decimal", "type": "string" } }, "type": "object" }, "gross_captured": { "format": "decimal", "type": "string" }, "net": { "format": "decimal", "type": "string" }, "platform_fees_earned": { "format": "decimal", "type": "string" }, "processor_fees_paid": { "format": "decimal", "type": "string" }, "refunded": { "format": "decimal", "type": "string" }, "unexplained": { "format": "decimal", "type": "string" } }, "type": "object" }, "net": { "format": "decimal", "type": "string" }, "platform": { "description": "The platform's own lines, each bucket the net of its lines.", "properties": { "line_count": { "type": "integer" }, "net": { "format": "decimal", "type": "string" }, "other": { "format": "decimal", "type": "string" }, "payouts": { "format": "decimal", "type": "string" }, "reserves": { "format": "decimal", "type": "string" }, "stripe_fees": { "format": "decimal", "type": "string" }, "tax_on_fees": { "format": "decimal", "type": "string" }, "unattributed": { "format": "decimal", "type": "string" } }, "type": "object" }, "ties_to_stripe": { "properties": { "activity": { "properties": { "count": { "type": "integer" }, "fee": { "format": "decimal", "type": "string" }, "gross": { "format": "decimal", "type": "string" }, "net": { "format": "decimal", "type": "string" } }, "type": "object" }, "balance_change": { "format": "decimal", "type": "string" }, "payouts": { "properties": { "count": { "type": "integer" }, "net": { "format": "decimal", "type": "string" } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "type": "array" }, "unplaced_count": { "type": "integer" } }, "required": [ "month", "from", "to", "timezone", "line_count", "account_count", "unplaced_count", "totals" ], "type": "object" } } }, "description": "The platform's month.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`month` is missing or not `YYYY-MM`." } }, "security": [ { "aerandil_oauth": [ "tenant_admin:write" ] } ], "summary": "Read the platform's whole month on its own Stripe balance", "tags": [ "finance" ] } }, "/v1/portal/token": { "post": { "description": "Exchange a human's verified portal session (WorkOS) — or the authorization code from the AuthKit redirect, which the kernel exchanges with WorkOS itself — for a tenant-scoped bearer token that runs as a `User` principal (cloud 0006 §10). \n\n**The human behind the token is a `staff_member` when one claims the identity** (Ithaca's desk, 2026-09-09): a staff record whose `identity_subject` is the provider's subject — or, on a code exchange, the one active employee carrying the provider's verified email, bound on that first sign-in through `update_staff_member_profile`. The token's principal is then that record, the scope vector follows the employee's role (a tenant `admin` keeps the admin grant on top), and the lifetime is a shift (`AERANDIL_STAFF_SESSION_TTL`). An inactive staff record that claims the identity is refused (`403`). Otherwise the token runs as the provider subject with the organization role's vector for the service-token lifetime. An optional `scope` parameter narrows within the grant but never widens it. \n\nPublic endpoint — the caller authenticates with the portal session, not a prior bearer. Returns `501` when no identity provider is configured on the cell.", "operationId": "aerandil_portal_token", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortalTokenRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortalTokenResponse" } } }, "description": "Token minted. `scope` is the role-derived set, intersected with the `scope` request parameter when present; `staff_member_id` names the employee the token runs as, when one claims the identity." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The portal session or code was missing, expired, or rejected." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The staff record that claims this identity is inactive." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "More than one staff record claims this identity (`ambiguous_staff_identity`)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Neither or both of `session` and `code` were given." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No identity provider is configured on this cell." } }, "security": [], "summary": "Exchange a portal session or sign-in code for a scoped user token", "tags": [ "oauth" ] } }, "/v1/print/epson/sdp": { "post": { "description": "Where a printer configured for Epson Server Direct Print comes for its work. The printer POSTs a form (`application/x-www-form-urlencoded`): `ConnectionType=GetRequest` asks for the next job and is answered `200 text/xml` with `` — one `` with `` (`devid`, `timeout`, `printjobid`) and `` (the receipt's ``) — or an empty `200` when nothing is queued; `ConnectionType=SetResponse` reports the jobs' results in `ResponseFile` (``) and is answered an empty `200`. Public: a printer carries no bearer. The printer names its tenant (`tenant` query parameter), its device by `ID` (the device's `code`) and proves it with the secret whose SHA-256 the device holds (`print_secret_hash`), as the HTTP Basic password or a `Password` form field. Refusals carry no body: `401` (not an active printer holding that secret; with a Basic challenge), `429` (more than a burst of 5 polls, refilled at one a second), `404` (`AERANDIL_PRINT_SDP_ENABLED` is off).", "operationId": "epson_server_direct_print", "parameters": [ { "description": "The tenant the printer is registered under (not a secret).", "in": "query", "name": "tenant", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "properties": { "ConnectionType": { "enum": [ "GetRequest", "SetResponse" ], "type": "string" }, "ID": { "description": "The printer's Server Direct Print ID: its device code.", "type": "string" }, "Name": { "type": "string" }, "Password": { "description": "The printer's secret, when not sent as HTTP Basic.", "type": "string" }, "ResponseFile": { "description": "`SetResponse` only: the `` document.", "type": "string" } }, "required": [ "ConnectionType" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "text/xml": { "schema": { "type": "string" } } }, "description": "A job as ``, or an empty body." }, "401": { "description": "Not an active printer holding that secret (no body)." }, "404": { "description": "Server Direct Print is not enabled (no body)." }, "429": { "description": "Polling faster than a printer is set to (no body)." } }, "security": [], "summary": "A receipt printer's poll (Epson Server Direct Print)", "tags": [ "fnb" ] } }, "/v1/properties/{property_id}/merchant-account": { "post": { "description": "Creates the hotel's own Stripe account under the platform's (Stripe Connect, Express-style: Stripe verifies the hotel on its hosted form, the hotel gets Stripe's Express dashboard, the platform pays Stripe's fees) and records it with `open_merchant_account`. The account opens in `onboarding`; send the hotel to the onboarding link next. While the account is open but not yet `active`, card payments at the property are refused with `merchant_account_not_ready` rather than taken on the platform's account. If the ledger refuses the account after Stripe has made it, the Stripe account is deleted again. Operator only (`tenant_admin:write`): the platform signs the hotel up and sets its fee. `501` unless `AERANDIL_STRIPE_ENABLED=1`.", "operationId": "open_merchant_account", "parameters": [ { "description": "The property whose card payments will settle to the account.", "in": "path", "name": "property_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "country": { "description": "Where the hotel trades (ISO 3166-1 alpha-2). Fixed for the account's life.", "type": "string" }, "email": { "description": "The hotel's contact, prefilled on Stripe's form.", "format": "email", "type": "string" }, "fee_conversion_bps": { "description": "Stripe's currency-conversion fee, for the estimate. Defaults to the country's.", "maximum": 10000, "minimum": 0, "type": "integer" }, "fee_schedule": { "description": "The whole schedule, row by row: every card class online and card-present, once.", "items": { "$ref": "#/components/schemas/FeeScheduleRow" }, "type": "array" }, "markup_bps": { "description": "The platform's markup over Stripe's published rate for each card class, in basis points — the country's table plus this. Defaults to 40 (Stripe + 0.40%). Not with `fee_schedule`.", "type": "integer" } }, "required": [ "country" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "idempotent_replay": { "type": "boolean" }, "merchant_account_id": { "format": "uuid", "type": "string" }, "status": { "enum": [ "onboarding" ], "type": "string" } }, "required": [ "merchant_account_id", "status" ], "type": "object" } } }, "description": "The account, opened and waiting on the hotel.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`merchant_account_exists` — the property already has an account that is not closed." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The country is not an ISO 3166-1 alpha-2 code, or the fee is outside 0–10000 basis points." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No card rail is configured on this deployment." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`rail_unavailable` — the card processor could not be reached (a transport failure, a 5xx, a 429, or this request's key still running at the processor). No account was opened. Try again after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait before trying the same request again (RFC 9110 §10.2.3) — the queue's first backoff.", "schema": { "minimum": 0, "type": "integer" } } } } }, "security": [ { "aerandil_oauth": [ "tenant_admin:write" ] } ], "summary": "Open a property's merchant account", "tags": [ "finance" ] } }, "/v1/proposed-actions/{id}/confirm": { "post": { "description": "Accept a `proposed_action` and commit its chained `target_action`. This is the gold-standard human-in-the-loop commit: a confirming principal (staff, a guest surface, or an approval gate) accepts the proposal, and the **kernel — not the proposing agent — fires the frozen `target_action`** through the scope-checked action engine (Return-of-Control), then records the confirmation on the proposal (proposal 0030 §5.2). \n\n**confirmer_scope (0030 §6).** The caller must independently hold `actions:{target_action}:apply` for the proposal's target action — the proposal does not launder away authorization. That grant is a *dynamic per-proposal scope* (it depends on which action the proposal chains), so it is not enumerable as a static security entry here; the engine enforces it when the chained action fires. \n\n**Idempotent via `Idempotency-Key`.** The key is derived deterministically from the proposal id, so a crash between firing the action and recording the confirmation replays rather than double-fires; a replay adds `idempotent_replay: true`.", "operationId": "confirm_proposed_action", "parameters": [ { "description": "Object id (UUID v7, server-generated at create time).", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Opaque idempotency token (Stripe-shape). Repeated POSTs with the same key replay the original response within the cache TTL rather than creating a duplicate object.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "applied_params": { "description": "The confirmer's edit of the proposed parameters; absent → the frozen snapshot fires unchanged.", "type": "object" }, "return_modified": { "default": false, "description": "Include the chained action's modified-objects projection in the response.", "type": "boolean" } }, "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "applied_action_correlation_id": { "format": "uuid", "type": "string" }, "applied_target_ref": { "description": "Ref of the primary object the chained action touched, when it produced one.", "type": [ "string", "null" ] }, "chained_action": { "description": "The chained action's apply envelope; present only when `return_modified` is true.", "type": "object" }, "decision_status": { "const": "applied" }, "idempotent_replay": { "description": "Present and `true` only on an idempotent replay.", "type": "boolean" }, "proposed_action_id": { "format": "uuid", "type": "string" }, "target_action": { "type": "string" } }, "required": [ "proposed_action_id", "decision_status", "target_action", "applied_action_correlation_id" ], "type": "object" } } }, "description": "Confirmed. The chained action fired and the proposal is `applied`. A replay adds `idempotent_replay: true`." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The confirmer lacks the target action's `actions:{target_action}:apply` scope." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No such `proposed_action` for this tenant, or its target action is not registered." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`not_confirmable` — the proposal is in a terminal status or has expired." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`applied_params` is present but is not a JSON object." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] } ], "summary": "Confirm a proposed action (the kernel fires it)", "tags": [ "proposed_action" ] } }, "/v1/push-subscriptions": { "get": { "operationId": "list_push_subscriptions", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPushSubscriptionsResponse" } } }, "description": "The caller's own endpoints, newest first." }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "aerandil_oauth": [ "events:read" ] } ], "summary": "The caller's Web Push subscriptions", "tags": [ "push" ] }, "post": { "description": "Register the calling staff member's push endpoint — the `PushSubscription.toJSON()` shape plus the handset's origin (`app_url`) and whether it subscribed through `window.pushManager` (`declarative`, Declarative Web Push). The `(tenant, endpoint)` pair is the identity: registering an endpoint again re-binds it to the caller, which is how a shared handset follows whoever signs in. Bound to the token's `Principal::User`; a service credential is refused with 403. Accepts `Idempotency-Key`. The endpoint must be HTTPS (loopback HTTP in dev only).", "operationId": "create_push_subscription", "parameters": [ { "description": "Opaque idempotency token (Stripe-shape). Repeated POSTs with the same key replay the original response within the cache TTL rather than creating a duplicate object.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushSubscriptionRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushSubscriptionResponse" } } }, "description": "Registered (or re-bound).", "headers": { "Cache-Control": { "description": "Always `no-store`.", "schema": { "type": "string" } }, "Location": { "description": "`/v1/push-subscriptions/{id}`.", "schema": { "type": "string" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Unprocessable" } }, "security": [ { "aerandil_oauth": [ "events:read" ] } ], "summary": "Register (or re-bind) a Web Push subscription", "tags": [ "push" ] } }, "/v1/push-subscriptions/{id}": { "delete": { "description": "Removes the registration; the browser-side subscription is the handset's to keep or drop. Another staff member's row is `404`, never `403`.", "operationId": "delete_push_subscription", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "Dropped." }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "aerandil_oauth": [ "events:read" ] } ], "summary": "Drop one of the caller's Web Push subscriptions", "tags": [ "push" ] } }, "/v1/push/application-server-key": { "get": { "description": "The deployment's VAPID public key (RFC 8292), which a handset passes as `applicationServerKey` to `pushManager.subscribe()` before registering the resulting subscription. `404 push_not_configured` when the deployment sends no push notifications (`AERANDIL_PUSH_ENABLED` unset) — the handset's cue to offer nothing.", "operationId": "get_push_application_server_key", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushApplicationServerKeyResponse" } } }, "description": "The key.", "headers": { "Cache-Control": { "description": "Always `no-store`.", "schema": { "type": "string" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "aerandil_oauth": [ "events:read" ] } ], "summary": "The Web Push application server key", "tags": [ "push" ] } }, "/v1/readyz": { "get": { "description": "Returns 200 when the process is ready to serve traffic — checks Postgres connectivity. 503 when a dependency is down.", "operationId": "aerandil_readyz", "responses": { "200": { "description": "Service is ready." } }, "security": [], "summary": "Readiness probe", "tags": [ "system" ] } }, "/v1/reports/cancel_rate_by_channel": { "get": { "description": "Cancellation rate per (property, distribution channel) over a business-day window: bookings, cancellations, and the ratio, grouped by the reservation `source` enum. \n\n**Interim surface.** A hand-authored read over the `cancel_rate_by_channel` rollup; the conformed-metric (`MetricDef`) layer later supersedes it, adding the staleness tiers. \n\n**Scope: `objects:read`** (the data derives from reservations). Live data: always `Cache-Control: no-store`.", "operationId": "cancel_rate_by_channel_report", "parameters": [ { "description": "Narrow to one property; else all of the tenant's properties.", "in": "query", "name": "property_id", "required": false, "schema": { "format": "uuid", "type": "string" } }, { "description": "Inclusive lower bound on `period_start`, `YYYY-MM-DD`.", "in": "query", "name": "from", "required": false, "schema": { "type": "string" } }, { "description": "Inclusive upper bound on `period_start`, `YYYY-MM-DD`.", "in": "query", "name": "to", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "meta": { "properties": { "computed_at": { "description": "Newest row's compute timestamp, or null when there are no rows.", "type": [ "string", "null" ] } }, "required": [ "computed_at" ], "type": "object" }, "report": { "type": "string" }, "rows": { "items": { "properties": { "bookings": { "type": "integer" }, "cancel_rate": { "description": "`cancellations / bookings`, or null when `bookings == 0` — never NaN.", "type": [ "number", "null" ] }, "cancellations": { "type": "integer" }, "computed_at": { "type": "string" }, "period_start": { "type": "string" }, "property_id": { "format": "uuid", "type": "string" }, "source": { "description": "Distribution channel — the reservation `source` enum.", "type": "string" } }, "required": [ "property_id", "source", "period_start", "bookings", "cancellations", "cancel_rate", "computed_at" ], "type": "object" }, "type": "array" } }, "required": [ "report", "rows", "meta" ], "type": "object" } } }, "description": "The cancel-rate rows plus a computed-at meta block.", "headers": { "Cache-Control": { "description": "Always `no-store` — live data is never cacheable.", "schema": { "const": "no-store", "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`invalid_date` — `from` / `to` must be `YYYY-MM-DD`." } }, "security": [ { "aerandil_oauth": [ "objects:read" ] } ], "summary": "Cancellation rate by distribution channel", "tags": [ "analytics" ] } }, "/v1/reservations/{reservation_id}/cancellation-fee/collection": { "post": { "description": "The desk posts the fee (`post_cancellation_fee`) onto the cancelled booking's own account; this is the leg that moves the money — the no-show fee's collection, for the other retained fee. The booking's own card hold pays first (captured for no more than the account owes), and the stored card is charged off-session only for what the account still owes after it: a deposit already taken sits on that account as a credit, so the card is asked for `min(fee, outstanding)`, never the deposit again. An account that owes nothing is refused before the processor is asked. Name a card with `payment_card_id` or let the route pick, as for the no-show fee. The verb that records the outcome (`collect_cancellation_fee`) is the card rail's own: this route is the only way to it, under `actions:apply` or its own grant `actions:hospitality.action.collect_cancellation_fee:apply`. **Two of the three outcomes are not errors**: all three answer `200` with an `outcome`. `authentication_required` is not a decline — the fee stays owed and the guest is chased (`awaiting_guest`). The answer's `amount` is what this collection asked for — the hold's share (`hold_amount`) and the card's — and `fee` is the posted fee; the two differ by the deposit.", "operationId": "collect_cancellation_fee", "parameters": [ { "description": "The cancelled reservation carrying the posted fee.", "in": "path", "name": "reservation_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectCancellationFeeRequest" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectCancellationFeeResponse" } } }, "description": "The attempt was made and its outcome recorded — `collected`, `authentication_required`, or `uncollectible`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`merchant_account_not_ready`, `processor_key_reused`, `cancellation_fee_attempt_open` (the last collection, on another card, never recorded its outcome — retry without `payment_card_id`) or `cancellation_fee_attempt_unsettled` (an open attempt the ledger cannot ask the processor about — the operator settles it against Stripe first), as for the no-show fee." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`cancellation_fee_not_assessed` — no fee was posted for this reservation; `cancellation_fee_already_collected` — the money moved, and returning it is a refund; `cancellation_fee_nothing_outstanding` — the booking's account owes nothing toward the fee (the deposit on it covered it), so there is nothing to take; or `payment_card_not_chargeable` — a card named through `payment_card_id` that cannot be charged. A fee left `authentication_required` or `uncollectible` is not refused — both are retryable. The fee's own state is the at-most-once guard rather than `Idempotency-Key`." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No card rail is configured on this deployment." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`rail_unavailable` — the card processor could not be reached (a transport failure, a 5xx, a 429, or this request's key still running at the processor). The fee is not queued: it stands, and the desk takes it again. Try again after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait before trying the same request again (RFC 9110 §10.2.3) — the queue's first backoff.", "schema": { "minimum": 0, "type": "integer" } } } } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.collect_cancellation_fee:apply" ] } ], "summary": "Collect a posted cancellation fee off the booking hold and the stored card", "tags": [ "finance" ] } }, "/v1/reservations/{reservation_id}/no-show-fee/collection": { "post": { "description": "The night audit assesses the fee and posts the charge; this is the leg that moves the money, off-session against the card the guest left. The booking's own card hold pays first: a completed preauthorization's pending hold is captured for the fee (or all of it, when it is smaller — Stripe releases the rest), and the card is charged only for what it could not cover; `paid_by` says which. Name a card with `payment_card_id` or let the route pick — the one bound to this reservation first, then any active consented card the guest has on file (but not a card a pay page kept for another booking: its terms covered that booking), which is what makes it callable in a loop straight after the audit. The verb that records the outcome (`collect_no_show_fee`) is the card rail's own: this route is the only way to it, under `actions:apply` or its own grant `actions:hospitality.action.collect_no_show_fee:apply`. **Two of the three outcomes are not errors**, so all three answer `200` with an `outcome` rather than turning a card decision into an HTTP failure. `authentication_required` is the one to read carefully: the issuer demanded SCA on a charge with nobody present, which is not a decline — the fee stays on the books at full value and is collectable once the guest authenticates. A caller that treats it as a refusal writes off revenue it could still take.", "operationId": "collect_no_show_fee", "parameters": [ { "description": "The no-showed reservation carrying the assessed fee.", "in": "path", "name": "reservation_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectNoShowFeeRequest" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectNoShowFeeResponse" } } }, "description": "The attempt was made and its outcome recorded — `collected`, `authentication_required`, or `uncollectible`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`merchant_account_not_ready` — the property's card payments settle to its own merchant account, which Stripe has not yet let take charges; or `processor_key_reused` — a retry of an attempt that failed before its outcome was recorded reached Stripe on different terms (the property's account opened or closed, or its fee moved). Stripe refused it rather than charging twice; the first attempt may have taken the money, so check the Stripe dashboard first." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`no_show_fee_not_assessed` — nothing was assessed for this reservation; `no_show_fee_already_collected` — the money moved, and returning it is a refund rather than another collection; or `payment_card_not_chargeable` — a card named through `payment_card_id` that is expired or removed, unconsented, or tokenless. A card the caller chose and cannot charge is a mistake to correct rather than an uncollectible fee to write down. A fee left `authentication_required` or `uncollectible` is *not* refused — both are retryable, which is the point of recording them separately from `collected`. Note that the fee's own state is the at-most-once guard rather than `Idempotency-Key`: replaying a key after a successful collection answers `no_show_fee_already_collected`, not the original 200. The money still moves exactly once." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No card rail is configured on this deployment." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`rail_unavailable` — the card processor could not be reached (a transport failure, a 5xx, a 429, or this request's key still running at the processor). The fee is not queued: it stands, and the desk or the next night audit takes it again. Try again after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait before trying the same request again (RFC 9110 §10.2.3) — the queue's first backoff.", "schema": { "minimum": 0, "type": "integer" } } } } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.collect_no_show_fee:apply" ] } ], "summary": "Collect an assessed no-show fee off the stored card", "tags": [ "finance" ] } }, "/v1/reservations/{reservation_id}/virtual-card-setup-intents": { "post": { "description": "The rail makes a Stripe Customer for the booking's virtual card and stamps it — `metadata[aerandil_tenant]`, `[aerandil_merchant_account]` (the house's open account, absent for the platform's own), `[aerandil_reservation]` and `[aerandil_channel]` (the channel the booking came through, when it names one) — then mints a SetupIntent (`usage=off_session`) on it, tagged the same. The desk keys the channel's number into Stripe's own card field with the `client_secret`; the number never reaches Aerandil. A virtual card's Customer is the rail's to record, so this and `POST /v1/reservations/{reservation_id}/virtual-cards` are the path a channel's card takes to be charged on its activation date.", "operationId": "create_virtual_card_setup_intent", "parameters": [ { "description": "The booking the channel's card was funded for.", "in": "path", "name": "reservation_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupIntentResponse" } } }, "description": "Collection may begin.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No card rail is configured on this deployment." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`rail_unavailable` — the card processor could not be reached (a transport failure, a 5xx, a 429, or this request's key still running at the processor). No card field could be prepared. Try again after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait before trying the same request again (RFC 9110 §10.2.3) — the queue's first backoff.", "schema": { "minimum": 0, "type": "integer" } } } } }, "summary": "Begin collecting a channel's virtual card for a booking", "tags": [ "finance" ] } }, "/v1/reservations/{reservation_id}/virtual-cards": { "post": { "description": "Takes the SetupIntent id and the channel's terms, never the card's details: the intent must carry this deployment's tags for this booking (`setup_intent_not_for_this_booking` otherwise) and the merchant account the house settles to now — none when it has none (`setup_intent_not_for_this_account` otherwise) — and have `succeeded`, and the card is read back off Stripe and must hang off the intent's own Customer (`card_belongs_to_another_customer`). Recorded through the card rail's verb `record_saved_payment_card` as `card_format: virtual`, bound to the booking, with the Customer — the one way a virtual card gets the Customer its off-session activation charge needs. A token handed in through the public `store_payment_card` names no Customer and is refused at activation.", "operationId": "store_virtual_card", "parameters": [ { "description": "The booking the channel's card was funded for.", "in": "path", "name": "reservation_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreVirtualCardRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCardResponse" } } }, "description": "The channel's card is on file for the booking. The display triple only; the token is `payment.token`-marked.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`invalid_setup_intent_id` (not shaped `seti_` plus letters and digits; refused before the processor is asked), `setup_intent_mismatch`, `setup_intent_not_for_this_booking`, `setup_intent_not_for_this_account` (minted while the house settled to a different merchant account than it does now), `card_not_collected` or `card_belongs_to_another_customer`; or the channel's terms refused (`funded_amount` not positive)." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No card rail is configured on this deployment." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`rail_unavailable` — the card processor could not be reached (a transport failure, a 5xx, a 429, or this request's key still running at the processor). The channel's card was not stored. Try again after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait before trying the same request again (RFC 9110 §10.2.3) — the queue's first backoff.", "schema": { "minimum": 0, "type": "integer" } } } } }, "summary": "Record the channel's virtual card a completed SetupIntent saved", "tags": [ "finance" ] } }, "/v1/retrieval/search": { "post": { "description": "Embeds `query` and cosine-ranks it against the host-side retrieval index (AIP Increment 4, Option B: vanilla Postgres, no extension). Only unmarked String/Text/Enum properties are ever embedded, and every hit is re-hydrated through the caller's authorized read path — marking redaction applies and unreadable objects are dropped, never ranked into view. Returns `501` when the retrieval tier is disabled (`AERANDIL_RETRIEVAL_ENABLED` unset).", "operationId": "search_retrieval", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "limit": { "default": 10, "description": "Maximum hits returned (clamped to 1..100).", "maximum": 100, "minimum": 1, "type": "integer" }, "object_types": { "description": "Optional filter to these object-type api-names; defaults to every indexed type.", "items": { "type": "string" }, "type": "array" }, "query": { "description": "Natural-language query text.", "type": "string" } }, "required": [ "query" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" }, "properties": { "description": "The object's properties as the caller is cleared to see them (marking redaction applied).", "type": "object" }, "score": { "description": "Cosine similarity in [-1, 1], higher is closer.", "type": "number" } }, "required": [ "object_type", "id", "score", "properties" ], "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "Cosine-ranked, ACL-hydrated hits, best first.", "headers": { "Cache-Control": { "description": "Always `no-store` — live data.", "schema": { "const": "no-store", "type": "string" } } } }, "403": { "description": "Missing `objects:read` scope." }, "501": { "description": "The retrieval tier is disabled on this deployment." } }, "summary": "Semantic search over the tenant's indexed objects", "tags": [ "retrieval" ] } }, "/v1/scenarios/run": { "post": { "description": "Replays `steps` in order inside one transaction through the same guards, validation, and handlers as `/apply`, so later steps see earlier steps' writes. `commit=false` (default) stages the scenario: the response carries per-step effect sets plus the merged `diff` a real apply would produce, then everything rolls back — zero durable trace. `commit=true` applies the whole scenario atomically; any step's failure aborts every step. A step may target an object created by an earlier step via `{\"created_by_step\": k, \"object_type\": ...}` — positional, resolved at replay time. Requires the apply scope of every step's action; internal-runner actions are rejected. Bounded at 100 steps. `commit=true` accepts `Idempotency-Key`.", "operationId": "run_scenario", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "commit": { "default": false, "description": "`false` stages (diff + rollback); `true` applies atomically.", "type": "boolean" }, "steps": { "items": { "additionalProperties": false, "properties": { "action": { "description": "Registered action api-name (e.g. `hospitality.action.check_in`).", "type": "string" }, "params": { "additionalProperties": true, "description": "The step action's parameters — same flat canonical JSON as that action's `/apply` schema.", "type": "object" }, "target": { "description": "The step's target: an existing object, a positional reference to an object created by an earlier step, or absent for create-shaped actions.", "oneOf": [ { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "object_type": { "type": "string" } }, "required": [ "object_type", "id" ], "type": "object" }, { "additionalProperties": false, "properties": { "created_by_step": { "minimum": 0, "type": "integer" }, "object_type": { "type": "string" } }, "required": [ "created_by_step", "object_type" ], "type": "object" } ] } }, "required": [ "action" ], "type": "object" }, "maxItems": 100, "minItems": 1, "type": "array" } }, "required": [ "steps" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "commit_warnings": { "items": { "type": "object" }, "type": "array" }, "committed": { "type": "boolean" }, "diff": { "description": "Merged object diff across all steps (Created+Modified→Created, Created+Deleted→net nothing, Modified+Deleted→Deleted).", "items": { "properties": { "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "created", "modified", "deleted" ], "type": "string" }, "object_type": { "type": "string" } }, "required": [ "object_type", "id", "kind" ], "type": "object" }, "type": "array" }, "idempotent_replay": { "description": "Present and `true` when a committed run was replayed from the idempotency cache.", "type": "boolean" }, "steps": { "description": "Per-step apply responses, in step order.", "items": { "type": "object" }, "type": "array" } }, "required": [ "steps", "diff", "commit_warnings", "committed" ], "type": "object" } } }, "description": "The scenario outcome: per-step effect sets, the merged diff, commit-time warnings, and whether it committed.", "headers": { "Cache-Control": { "description": "Always `no-store` — live, per-run data.", "schema": { "const": "no-store", "type": "string" } } } }, "403": { "description": "A step's apply scope is missing, or a step names an internal-runner action." }, "422": { "description": "A step failed validation — nothing was applied." } }, "summary": "Run a multi-edit Scenario (staged or applied)", "tags": [ "scenarios" ] } }, "/v1/staff/{id}/handset-passcode": { "put": { "description": "Validates the PIN policy (6–12 digits), hashes it (Argon2id), and records the hash on the `staff_member` through the internal-runner action `set_staff_handset_passcode` — the raw PIN never enters an action's params, an event, or the MCP tool surface. An empty body (or `passcode: null`) clears the PIN. Requires `actions:apply`, the per-action grant for `set_staff_handset_passcode`, or `tenant_admin:write` — and, short of `tenant_admin:write`, the right person: a person sets their own (a desk bearer only inside a step-up window), and a manager sets a floor role's below them at a house they share (the front office's managers any floor role's, a housekeeping supervisor a housekeeper's). Nobody else sets anyone's.", "operationId": "aerandil_set_staff_handset_passcode", "parameters": [ { "description": "The `staff_member` id.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetHandsetPasscodeRequest" } } }, "required": false }, "responses": { "204": { "description": "PIN recorded or cleared.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The bearer holds none of the accepted grants, or is not a person who may set this staff member's PIN (`step_up_required` for one's own from a desk bearer without a fresh proof)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No such staff member in the caller's tenant." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The PIN violates the policy." } }, "summary": "Set or clear a staff member's handset PIN", "tags": [ "oauth" ] } }, "/v1/stays/{stay_id}/holds/top-up": { "post": { "description": "OPERA's \"Run Additional Authorization\": the top-up the stay's bill calls for now (`plan_hold_top_up` with `on_demand`) — the bill's balance, less what the stay's pending holds hold, plus the allowance of the incidental-hold rule its booking matches — carried out as the night audit would, whatever the house's threshold and never past its `max_per_stay`: a second hold for the excess on the card the stay's hold was taken on, off-session (the card must carry the guest's consent to charges the house initiates), or the hold raised in place where the card and the account allow incremental authorisation; past the credit limit at a house that charges (`set_credit_limit_overage`), the holds taken for the bill and the allowance held afresh. **A decline, an authentication demand, the house's merchant account not ready and an attempt the rail had to give up are outcomes, not errors**: `200` with `outcome = refused` and the reason, recorded on the stay for the desk (`hold_top_up.refused`). Stripe unreachable (since 2026-10-21): the stay's open attempt is queued for the card rail — `202`, a `rail_instruction` of kind `top_up` — and carried out by its drain under the attempt's own processor keys; a press while it is queued answers the same instruction. Needs the catch-all `actions:apply` or the route's own grant. `501` unless `AERANDIL_STRIPE_ENABLED=1`.", "operationId": "top_up_stay_hold", "parameters": [ { "description": "The in-house stay whose card hold is topped up.", "in": "path", "name": "stay_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "amount": { "format": "decimal", "type": [ "string", "null" ] }, "captured": { "format": "decimal", "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "idempotent_replay": { "type": "boolean" }, "outcome": { "enum": [ "nothing", "placed", "incremented", "charged", "refused" ], "type": "string" }, "payment_id": { "format": "uuid", "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "refusal": { "enum": [ "card_declined", "insufficient_funds", "authentication_required", "no_consent", "no_card", "max_reached", "other_currency", "processor_refused", "attempt_abandoned", null ], "type": [ "string", "null" ] }, "refusal_detail": { "type": [ "string", "null" ] }, "stay_id": { "format": "uuid", "type": "string" } }, "required": [ "stay_id", "outcome" ], "type": "object" } } }, "description": "What the rail did: nothing (with the reason), a hold placed or raised, the holds taken for the bill, or a refusal with its reason.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "202": { "content": { "application/json": { "schema": { "properties": { "already_queued": { "type": "boolean" }, "amount": { "format": "decimal", "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "idempotent_replay": { "type": "boolean" }, "kind": { "enum": [ "capture", "void", "refund", "charge_off_session", "top_up" ], "type": "string" }, "message": { "type": "string" }, "payment_id": { "format": "uuid", "type": [ "string", "null" ] }, "queued": { "const": true, "type": "boolean" }, "rail_instruction_id": { "format": "uuid", "type": "string" }, "state": { "enum": [ "queued", "sending" ], "type": "string" }, "stay_id": { "format": "uuid", "type": [ "string", "null" ] } }, "required": [ "queued", "rail_instruction_id", "kind", "state" ], "type": "object" } } }, "description": "Stripe could not be reached (a transport failure, a 5xx, a 429, or this attempt's key still running at Stripe), so the work was written down as a rail instruction and is taken when the rail is back — under the same processor key as this attempt, so it is never taken twice. A second request while it is queued answers the same instruction (`already_queued`); the desk may cancel it while it is still queued (`cancel_rail_instruction`).", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`idempotency_in_flight` — a request under this `Idempotency-Key` is still running; retry shortly. Or `rail_instruction_open` — another verb is already queued for this hold or stay; it is taken first." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`stay_not_in_house` — only an in-house stay's hold is topped up; or `idempotency_key_mismatch` — the key was used for another stay's top-up." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No card rail is configured on this deployment." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`rail_unavailable` — Stripe could not be reached and no top-up attempt was open on the stay, so nothing reached it: try again (`Retry-After`). With an attempt open the press is queued instead (`202`).", "headers": { "Retry-After": { "description": "Seconds to wait before trying the same request again (RFC 9110 §10.2.3) — the queue's first backoff.", "schema": { "minimum": 0, "type": "integer" } } } } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.record_hold_top_up:apply" ] } ], "summary": "Top up an in-house stay's card hold now", "tags": [ "finance" ] } }, "/v1/stays/{stay_id}/post-stay-charges/collection": { "post": { "description": "The leg that moves the money for charges found after departure (`post_departed_charge`, inside the house's post-stay window): the hold check-out kept is captured up to what the bill owes — a partial capture releases the rest — and anything left is charged off-session to the card on file (one bound to the booking, else the guest's newest active card carrying off-session consent). The bill closes again once it owes nothing. **An SCA demand and a decline are outcomes, not errors**: the route answers `200` with what was taken and a `refusal` naming why the rest was not — `authentication_required` keeps the charge owed until the guest authenticates. Needs the no-show collection's scope. `501` unless `AERANDIL_STRIPE_ENABLED=1`.", "operationId": "collect_post_stay_charges", "parameters": [ { "description": "The departed stay whose bill carries the late charges.", "in": "path", "name": "stay_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "balance": { "format": "decimal", "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "folio_id": { "format": "uuid", "type": "string" }, "from_card": { "format": "decimal", "type": [ "string", "null" ] }, "from_hold": { "format": "decimal", "type": [ "string", "null" ] }, "idempotent_replay": { "type": "boolean" }, "refusal": { "enum": [ "authentication_required", "declined", "no_card", null ], "type": [ "string", "null" ] }, "refusal_detail": { "type": [ "string", "null" ] }, "stay_id": { "format": "uuid", "type": "string" } }, "required": [ "stay_id", "folio_id" ], "type": "object" } } }, "description": "The attempt was made and recorded: what the kept hold and the card took, and why the rest was not taken.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "202": { "content": { "application/json": { "schema": { "properties": { "already_queued": { "type": "boolean" }, "amount": { "format": "decimal", "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "idempotent_replay": { "type": "boolean" }, "kind": { "enum": [ "capture", "void", "refund", "charge_off_session", "top_up" ], "type": "string" }, "message": { "type": "string" }, "payment_id": { "format": "uuid", "type": [ "string", "null" ] }, "queued": { "const": true, "type": "boolean" }, "rail_instruction_id": { "format": "uuid", "type": "string" }, "state": { "enum": [ "queued", "sending" ], "type": "string" }, "stay_id": { "format": "uuid", "type": [ "string", "null" ] } }, "required": [ "queued", "rail_instruction_id", "kind", "state" ], "type": "object" } } }, "description": "Stripe could not be reached (a transport failure, a 5xx, a 429, or this attempt's key still running at Stripe), so the work was written down as a rail instruction and is taken when the rail is back — under the same processor key as this attempt, so it is never taken twice. A second request while it is queued answers the same instruction (`already_queued`); the desk may cancel it while it is still queued (`cancel_rail_instruction`).", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`merchant_account_not_ready` — the house's card payments settle to its own merchant account, which Stripe has not yet let take charges; or `processor_key_reused` — a retry reached Stripe on different terms. Or `rail_instruction_open` — another verb is already queued for this hold or stay; it is taken first." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`stay_not_departed`, `post_stay_charging_off` (the guest left with the house's window off), or `nothing_to_collect` (the bill owes nothing)." }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No card rail is configured on this deployment." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`rail_unavailable` — the card processor could not be reached (a transport failure, a 5xx, a 429, or this request's key still running at the processor). Answered only when no collection attempt was open, so nothing reached the processor; otherwise the collection is queued (`202`). Try again after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait before trying the same request again (RFC 9110 §10.2.3) — the queue's first backoff.", "schema": { "minimum": 0, "type": "integer" } } } } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.collect_no_show_fee:apply" ] } ], "summary": "Take a departed stay's late charges off its card", "tags": [ "finance" ] } }, "/v1/stripe/publishable-key": { "get": { "description": "Served rather than baked into the desk's build, so one artefact runs against a sandbox and a live account without being rebuilt — and so a deployment cannot quietly point a live desk at a test account, which is the failure that looks like everything working until no money has moved. Public key material, but still `no-store`: it names which account this deployment is, and a cached copy outliving a key rotation would send a desk to the wrong one.", "operationId": "get_stripe_publishable_key", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripePublishableKeyResponse" } } }, "description": "The publishable key.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`AERANDIL_STRIPE_PUBLISHABLE_KEY` is unset, so this deployment cannot collect a card." } }, "summary": "Which processor account to tokenise at", "tags": [ "finance" ] } }, "/v1/stripe/setup-intents": { "post": { "description": "Mints a SetupIntent whose `client_secret` the browser completes with the *publishable* key. `usage=off_session` is always set, because SCA requires the cardholder to authenticate up front if the property intends to charge them later — a card saved without it may simply be declined when the no-show fee is attempted, at the exact moment the guest is unreachable. The guest's existing cards at this merchant name the processor customer to reuse; the first card mints one — one Customer per guest per merchant account, since the stored-credential agreement is with the merchant on the statement.", "operationId": "create_card_setup_intent", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupIntentRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupIntentResponse" } } }, "description": "Collection may begin.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No card rail is configured on this deployment." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`rail_unavailable` — the card processor could not be reached (a transport failure, a 5xx, a 429, or this request's key still running at the processor). No card field could be prepared. Try again after `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait before trying the same request again (RFC 9110 §10.2.3) — the queue's first backoff.", "schema": { "minimum": 0, "type": "integer" } } } } }, "summary": "Begin collecting a card without charging it", "tags": [ "finance" ] } }, "/v1/switchover/{connector_id}/cut-over": { "post": { "description": "The switchover's decision: stop treating the connector's source PMS as the system of record. **Refused unless it is safe**: the route first reads the shadow comparison (`GET /v1/analytics/switchover-shadow`) and answers `409 cutover_blocked` — the counts in the message, the blocking discrepancies (at most 50) and the summary in `parameters` — while anything blocks; it never asks the caller to underwrite an unsafe cutover. A connector already cut over answers `409 already_cut_over` (with its `cut_over_at`), a retired one `409 connector_retired`, any other not `active` one `409 connector_not_active`. \n\nThen, in one transaction (`cut_over_connector`): the connector is paused with a reason naming the decision and stamped `cut_over_at` / `cut_over_by` / `cut_over_summary` (the pre-flight it was taken on), and each named channel conduit is brought live (paused → active; a conduit pending mapping, suspended, closed or unmapped refuses the whole gesture, `422`, before anything is written). In-house guests are never re-keyed. \n\nThen each conduit is published in full: a `full` `channel_publication_run` over today to the conduit's horizon, its cells seeded so the dispatcher sends the whole of the house's availability, rates and restrictions — clearing closures the partner still holds from the old PMS. A conduit the partner's 24-hour floor refuses is reported `skipped` (the cutover stands; publish later), one that fails `failed`. \n\nNeeds the catch-all `actions:apply` or the route's own grant; not from a desk bound to one property. Accepts an `Idempotency-Key`. Live data: `Cache-Control: no-store`.", "operationId": "cut_over_connector", "parameters": [ { "description": "The connector object's id.", "in": "path", "name": "connector_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "channel_connection_ids": { "description": "The channel conduits to bring live with the cutover: each mapped and paused (or already active).", "items": { "format": "uuid", "type": "string" }, "type": "array" }, "reason": { "description": "Why, recorded on the connector.", "type": "string" } }, "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "conduits": { "items": { "properties": { "cells_seeded": { "description": "Outbox cells the horizon seed wrote.", "format": "int64", "type": "integer" }, "full_publication": { "enum": [ "started", "skipped", "failed" ], "type": "string" }, "id": { "format": "uuid", "type": "string" }, "note": { "description": "Why a publication was skipped or failed.", "type": "string" }, "publication_run_id": { "description": "The `full` channel_publication_run opened.", "format": "uuid", "type": "string" } }, "required": [ "id", "full_publication", "cells_seeded" ], "type": "object" }, "type": "array" }, "connector_business_id": { "type": "string" }, "connector_id": { "format": "uuid", "type": "string" }, "cut_over_at": { "format": "date-time", "type": "string" }, "cut_over_by": { "type": "string" }, "idempotent_replay": { "description": "Present (true) when an Idempotency-Key replay answered.", "type": "boolean" }, "preflight": { "description": "The shadow comparison the decision was taken on, as recorded on the connector.", "properties": { "as_of": { "format": "date-time", "type": "string" }, "business_date": { "format": "date", "type": "string" }, "streams": { "description": "Per staged stream, its rows by load outcome. A staged row with no load outcome yet is pending.", "items": { "properties": { "deferred": { "type": "integer" }, "loaded": { "type": "integer" }, "mapping_ref": { "description": "The connector's mapping for the stream (`name@version`); null when it carries none.", "type": [ "string", "null" ] }, "pending": { "type": "integer" }, "rejected": { "type": "integer" }, "stream": { "type": "string" } }, "required": [ "stream", "mapping_ref", "loaded", "pending", "rejected", "deferred" ], "type": "object" }, "type": "array" }, "summary": { "properties": { "advisory": { "type": "integer" }, "blocking": { "type": "integer" }, "folios_agreeing": { "type": "integer" }, "folios_compared": { "type": "integer" } }, "required": [ "folios_compared", "folios_agreeing", "blocking", "advisory" ], "type": "object" } }, "required": [ "summary", "as_of", "business_date", "streams" ], "type": "object" }, "status": { "enum": [ "paused" ], "type": "string" } }, "required": [ "connector_id", "connector_business_id", "status", "cut_over_at", "cut_over_by", "conduits", "preflight" ], "type": "object" } } }, "description": "Cut over; each conduit's full publication reported.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Token lacks `actions:apply` and the route's own grant, or is a desk session bound to one property." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No such connector, or no such channel conduit." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The cutover is refused: `cutover_blocked` (the shadow comparison has blocking discrepancies — `parameters.blocking`, `parameters.by_kind`, `parameters.summary`), `already_cut_over`, `connector_retired`, `connector_not_active`, `connector_pipeline_invalid`, or an Idempotency-Key still in flight." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Malformed body, or a named conduit cannot be brought live (pending mapping, suspended, closed or unmapped)." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.cut_over_connector:apply" ] } ], "summary": "Cut a house over from its source PMS", "tags": [ "connectors" ] } }, "/v1/switchover/{connector_id}/roll-back": { "post": { "description": "The cutover reversed (`roll_back_connector_cutover`, one transaction): the connector is active again and syncing, its `cut_over_*` record cleared (the events keep the history) and the reason appended to its notes; the conduits the cutover brought live are paused with a reason naming the rollback — a suspended one is left to the partner that stopped it, a closed one where it ended. \n\nThe answer counts the bookings taken in Aerandil since the cutover that the source PMS never saw (`booked_in_aerandil_since_cutover`: live reservations at a house this connector feeds, created after `cut_over_at`, not carrying the connector's external ref) — they must be keyed back into the old PMS. `409 not_cut_over` when there is no cutover to reverse, `409 connector_retired` for a retired connector. \n\nNeeds the catch-all `actions:apply` or the route's own grant; not from a desk bound to one property. Accepts an `Idempotency-Key`. Live data: `Cache-Control: no-store`.", "operationId": "roll_back_connector_cutover", "parameters": [ { "description": "The connector object's id.", "in": "path", "name": "connector_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "reason": { "description": "Why, recorded on the connector and the paused conduits.", "minLength": 1, "type": "string" } }, "required": [ "reason" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "booked_in_aerandil_since_cutover": { "format": "int64", "type": "integer" }, "booked_in_aerandil_since_cutover_ids": { "description": "Those reservations' ids (at most 500).", "items": { "format": "uuid", "type": "string" }, "type": "array" }, "conduits_left": { "description": "Conduits the rollback did not pause (suspended or closed).", "items": { "properties": { "id": { "format": "uuid", "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "status" ], "type": "object" }, "type": "array" }, "conduits_paused": { "items": { "format": "uuid", "type": "string" }, "type": "array" }, "connector_business_id": { "type": "string" }, "connector_id": { "format": "uuid", "type": "string" }, "idempotent_replay": { "type": "boolean" }, "resumed": { "type": "boolean" }, "rolled_back_cut_over_at": { "description": "The cutover reversed.", "format": "date-time", "type": "string" }, "status": { "enum": [ "active" ], "type": "string" } }, "required": [ "connector_id", "connector_business_id", "resumed", "status", "rolled_back_cut_over_at", "conduits_paused", "conduits_left", "booked_in_aerandil_since_cutover", "booked_in_aerandil_since_cutover_ids" ], "type": "object" } } }, "description": "Rolled back.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Token lacks `actions:apply` and the route's own grant, or is a desk session bound to one property." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No such connector." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`not_cut_over` (nothing to roll back), `connector_retired`, `connector_pipeline_invalid`, or an Idempotency-Key still in flight." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Malformed body, or an empty reason." } }, "security": [ { "aerandil_oauth": [ "actions:apply" ] }, { "aerandil_oauth": [ "actions:hospitality.action.roll_back_connector_cutover:apply" ] } ], "summary": "Roll a cutover back to the source PMS", "tags": [ "connectors" ] } }, "/v1/tenant-erasure-requests": { "post": { "description": "Hard-delete every `objects` and `links` row for a single `tenant_id` in one transaction. The contract-driven offboarding pathway — distinct from the per-row Article 17 endpoint at `/v1/erasure-requests`. \n\n**Operator-level scope: `tenant_admin:write`.** A tenant token cannot legitimately carry this; the caller is an Aerandil operator administering the contract that governs `tenant_id`'s lifecycle. \n\n**`events` is preserved.** The append-only audit log carries no PII (only metadata); retaining it post-tenant-erasure keeps the record-of-action intact for the regulator and the operator's compliance archive. \n\n**Single transaction.** A partial decommission would be worse than no decommission — it leaves rows visible after the operator thinks they're gone. \n\nIdempotent via `Idempotency-Key`.", "operationId": "create_tenant_erasure_request", "parameters": [ { "description": "Opaque idempotency token (Stripe-shape). Repeated POSTs with the same key replay the original response within the cache TTL rather than creating a duplicate object.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantErasureRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantErasureResponse" } } }, "description": "Tenant decommissioned. Counts surface for the operator's audit log; the response is mostly informational since the action is irreversible.", "headers": { "Cache-Control": { "description": "Always `no-store`.", "schema": { "const": "no-store", "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing the `tenant_admin:write` scope. Tenant- level tokens MUST NOT carry this scope." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Body invalid — `invalid_body` or `invalid_idempotency_key`." } }, "security": [ { "aerandil_oauth": [ "tenant_admin:write" ] } ], "summary": "Operator-level erasure of a full tenant", "tags": [ "compliance" ] } }, "/v1/tenant-export-requests": { "post": { "description": "Stream the tenant's full footprint as `application/x-ndjson` — one JSON object per line, ordered objects → links → events, ascending within each section. Backs the GDPR Article 20 portability commitment and the contractual right to data return on offboarding. \n\n**Operator-level scope: `tenant_admin:write`.** Same contract surface as the per-tenant erasure endpoint; a tenant cannot legitimately exfiltrate itself via API. \n\n**Snapshot semantics.** All three sub-queries run inside one `REPEATABLE READ` transaction, so the dump reflects a single consistent snapshot — concurrent writes during the stream don't surface as half-committed state. \n\n**Mid-stream errors** are signalled by a final NDJSON line of the form `{\"kind\":\"error\",\"message\":\"...\"}` — headers were already sent so the wire status stays `200`; the in-band error line is the only signal a consumer who tails the body can observe. \n\n**Not idempotent.** Each call materialises a fresh dump; retries re-run the export. A streamed response is hard to replay safely from a cache anyway (the body is produced once and forgotten). \n\n**Reads through the admin pool** (`BYPASSRLS`) — the export crosses the per-tenant RLS boundary by definition; tenant scoping comes from the explicit `WHERE tenant_id = $1` predicate, not the GUC.", "operationId": "create_tenant_export_request", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantExportRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/TenantExportLine" }, "x-itemSchema": { "$ref": "#/components/schemas/TenantExportLine" } } }, "description": "Streaming NDJSON dump. Each line is one `TenantExportLine` object (object / link / event / error). An empty tenant produces a 200 with an empty body.", "headers": { "Cache-Control": { "description": "Always `no-store` — streaming, not cacheable.", "schema": { "const": "no-store", "type": "string" } }, "Content-Type": { "description": "Always `application/x-ndjson`.", "schema": { "const": "application/x-ndjson", "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing the `tenant_admin:write` scope. Tenant- level tokens MUST NOT carry this scope." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Body invalid — `invalid_body` or unknown fields." } }, "security": [ { "aerandil_oauth": [ "tenant_admin:write" ] } ], "summary": "GDPR Article 20 streaming export of a full tenant", "tags": [ "compliance" ] } }, "/v1/tenant-import-requests": { "post": { "description": "Load a tenant's footprint — the `application/x-ndjson` body produced by `POST /v1/tenant-export-requests` — verbatim into this cell. The write-side half of the tenant- relocation protocol (cloud proposal 0007 §8). \n\n**Operator-level scope: `tenant_admin:write`.** Same surface as export and per-tenant erasure. \n\n**Verbatim, not replayed.** Rows load exactly as the source held them — `version`, soft-delete state, link temporal windows + `properties`, and the portable per-tenant ordinal `tenant_seq` are all preserved, and no new events are emitted. The global `seq` and CDC `commit_xid` are reassigned by this cell. \n\n**Atomic + idempotent.** The whole dump loads in one transaction (all-or-nothing); every insert is `ON CONFLICT DO NOTHING` on the row's natural key, so a retried import skips already-present rows (counted, not errored) — the basis for crash resumption. \n\n**Single-tenant.** Every row's `tenant_id` must equal the `tenant_id` query parameter; a foreign row aborts with `422 tenant_mismatch`, and an incomplete dump (an export `{\"kind\":\"error\"}` trailer) with `422 incomplete_export`. \n\n**NDJSON is the small-tenant path** — the dump+load freezes the tenant for the whole transfer. A large tenant relocates via row-filtered logical replication (proposal 0007 §3). \n\n**Writes through the admin pool** (`BYPASSRLS`); tenant isolation is the single-tenant check, not the RLS GUC.", "operationId": "create_tenant_import_request", "parameters": [ { "description": "The tenant every imported row must belong to.", "in": "query", "name": "tenant_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/TenantExportLine" }, "x-itemSchema": { "$ref": "#/components/schemas/TenantExportLine" } } }, "description": "An `application/x-ndjson` export stream — one `TenantExportLine` (object / link / event) per line.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantImportSummary" } } }, "description": "Import committed. Per-table tally of rows loaded vs. skipped (already present).", "headers": { "Cache-Control": { "description": "Always `no-store` — a live operation result.", "schema": { "const": "no-store", "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing the `tenant_admin:write` scope. Tenant- level tokens MUST NOT carry this scope." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Body invalid (`invalid_body`), a row's `tenant_id` differs from the target (`tenant_mismatch`), or the dump is incomplete (`incomplete_export`)." } }, "security": [ { "aerandil_oauth": [ "tenant_admin:write" ] } ], "summary": "Verbatim NDJSON import of a full tenant (the relocation counterpart of export)", "tags": [ "compliance" ] } }, "/v1/tenant-verify-digest": { "get": { "description": "Return an independent per-table `count` and content `checksum` for the tenant's objects / links / events (cloud proposal 0007 §4 step 5). The cross-cell relocation cutover job reads this from the source and the target cell and refuses to switch traffic until the two fingerprints agree — a re-query of each cell's actual persisted state, independent of the import's self-reported tally. The checksum covers exactly the portable columns the import preserves verbatim (events fold on the portable `tenant_seq`, never the source-local `seq` / `commit_xid`). Reads stay live in every write-mode. \n\n**Operator-level scope: `tenant_admin:write`** (same surface as tenant export / import / write-mode / erasure).", "operationId": "get_tenant_verify_digest", "parameters": [ { "description": "The tenant whose footprint is fingerprinted.", "in": "query", "name": "tenant_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantVerifyDigest" } } }, "description": "The tenant's per-table count + content checksum." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing the `tenant_admin:write` scope. Tenant-level tokens MUST NOT carry this scope." } }, "security": [ { "aerandil_oauth": [ "tenant_admin:write" ] } ], "summary": "Fingerprint a tenant's footprint (relocation verify gate)", "tags": [ "compliance" ] } }, "/v1/tenant-write-mode": { "get": { "description": "Return the tenant's current write-mode (`active` | `read_only` | `relocated`). A tenant whose mode was never set reads back `active` with null provenance. \n\n**Operator-level scope: `tenant_admin:write`** (same surface as tenant export / import / erasure).", "operationId": "get_tenant_write_mode", "parameters": [ { "description": "The tenant whose write-mode is read or set.", "in": "query", "name": "tenant_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantWriteModeRecord" } } }, "description": "The tenant's write-mode record." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing the `tenant_admin:write` scope. Tenant-level tokens MUST NOT carry this scope." } }, "security": [ { "aerandil_oauth": [ "tenant_admin:write" ] } ], "summary": "Read a tenant's write-mode", "tags": [ "compliance" ] }, "put": { "description": "Set the tenant's write-mode. Setting `read_only` is the quiesce step of a cross-cell relocation cutover (cloud proposal 0007 §4 step 3): while `read_only`, the tenant's writes are refused at the store's write-gate and surface as **503 + `Retry-After`** on every write endpoint, while reads stay live. Setting `relocated` is the post-cutover ownership flip (0007 §5): the Hub flips the *source* cell to not-owner once the tenant has been rebound to its new cell, and a straggler write that still resolves here is refused with **421 Misdirected Request** (terminal — re-resolve to the owning cell), while reads stay live. Setting `active` lifts either state. \n\n**Idempotent**: PUT replaces a singleton operational state, so it carries no `Idempotency-Key`, and no `If-Match` (this is operator state, not a versioned object — last writer wins). \n\n**Operator-level scope: `tenant_admin:write`.**", "operationId": "set_tenant_write_mode", "parameters": [ { "description": "The tenant whose write-mode is read or set.", "in": "query", "name": "tenant_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetTenantWriteModeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantWriteModeRecord" } } }, "description": "The persisted write-mode record." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing the `tenant_admin:write` scope. Tenant-level tokens MUST NOT carry this scope." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Body invalid — unknown field or unrecognised `mode`." } }, "security": [ { "aerandil_oauth": [ "tenant_admin:write" ] } ], "summary": "Set a tenant's write-mode (relocation quiesce / ownership flip)", "tags": [ "compliance" ] } }, "/v1/watchtower/contests": { "get": { "description": "The platform's review queue for Watchtower, the card rail's federated fraud network: every `fraud_network_signal` a desk contested (`contest_fraud_network_signal`), across every tenant, most recently contested first — the house it was given to, when and why it was contested, the answer's buckets, `band_floor` and `floor_basis` — and the contributions behind it: every `fraud_network_contribution` carrying one of the digests the answer kept, under its salt epoch, within the two-year look-back the answer was read with. A contribution is listed whatever its status now, naming its house, outcome, status and source; `counts` says whether the next answer still counts it (active, its house still consenting), `own_house` whether it is the contesting house's own, and `after_answer` whether it was contributed after the answer (so did not shape it). An answer frozen before its digests were kept (2026-11-03) lists none (`traceable: false`). The platform operator's read (`tenant_admin:write`), cleared to read `internal.restricted` (`markings:internal.restricted:read`): `403` without either, `insufficient_clearance` without the second.", "operationId": "list_watchtower_contests", "parameters": [ { "description": "At most this many contests (default 50).", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 200, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchtowerContestList" } } }, "description": "The contested answers, newest contest first.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Unprocessable" } }, "security": [ { "aerandil_oauth": [ "tenant_admin:write", "markings:internal.restricted:read" ] } ], "summary": "List the Watchtower answers houses contested, with the contributions behind each", "tags": [ "finance" ] } }, "/v1/watchtower/contributions/{contribution_id}/withdraw": { "post": { "description": "The platform's review of a contest decides a contribution behind it should not stand: it is taken back out of the network on the contributing house's behalf — the house's own `withdraw_fraud_signal`, run in its tenant by the card rail, recorded `withdrawn_by = platform` with the reason prefixed `platform review ()`. The next answer for the card no longer counts it; answers already given stand as given. The house sees the withdrawal on its own ledger and event log (`fraud_network.contribution_withdrawn`). `404` for an id that is no live contribution anywhere, `409 already_withdrawn` for one already out. The platform operator's (`tenant_admin:write`), cleared to read `internal.restricted`.", "operationId": "withdraw_watchtower_contribution", "parameters": [ { "description": "The fraud_network_contribution, in any tenant.", "in": "path", "name": "contribution_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchtowerWithdrawRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchtowerWithdrawResponse" } } }, "description": "Withdrawn; the contribution as it now reads.", "headers": { "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`already_withdrawn` — the contribution is already out of the network." }, "422": { "$ref": "#/components/responses/Unprocessable" } }, "security": [ { "aerandil_oauth": [ "tenant_admin:write", "markings:internal.restricted:read" ] } ], "summary": "Withdraw a house's Watchtower contribution on its behalf", "tags": [ "finance" ] } }, "/v1/webhook-subscriptions": { "get": { "description": "Returns every subscription owned by the calling tenant. Tenant scoping is automatic — a token issued for tenant A cannot enumerate tenant B's subscriptions. \n\nThe `signing_key` is never echoed by list/get — only the `primary_key_fingerprint` (and `secondary_key_fingerprint` during rotation).", "operationId": "list_webhook_subscriptions", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWebhookSubscriptionsResponse" } } }, "description": "Subscriptions for the calling tenant." } }, "security": [ { "aerandil_oauth": [ "webhooks:read" ] } ], "summary": "List webhook subscriptions", "tags": [ "webhooks" ] }, "post": { "description": "Register a receiver URL plus an optional `object_types` filter and a starting position. Returns the freshly generated `signing_key` exactly once — record it in your secret vault; subsequent reads expose only the fingerprint. \n\nThe `start_position` defaults to `now`: only events past the current head are delivered. Pick `beginning` to replay the full event log (useful for backfill / historical projection rebuilds). \n\nAccepts `Idempotency-Key` (Stripe shape — see [draft-ietf-httpapi-idempotency-key-header]). A retry with the same key returns the same response, including the original `signing_key`. \n\nReceiver URL must use HTTPS (loopback HTTP allowed in dev only — see `validate_url` in `webhooks/handlers.rs`).", "operationId": "create_webhook_subscription", "parameters": [ { "description": "Opaque idempotency token (Stripe-shape). Repeated POSTs with the same key replay the original response within the cache TTL rather than creating a duplicate object.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookSubscriptionRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionWithKeyResponse" } } }, "description": "Subscription created. The `signing_key` is returned only here and on rotate-key — record it now or rotate to get a new one.", "headers": { "Cache-Control": { "description": "Always `no-store`.", "schema": { "const": "no-store", "type": "string" } }, "Location": { "description": "`/v1/webhook-subscriptions/{id}` for the created resource.", "schema": { "type": "string" } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation error — `invalid_url`, malformed body, unknown fields, or invalid `Idempotency-Key`." } }, "security": [ { "aerandil_oauth": [ "webhooks:write" ] } ], "summary": "Create a webhook subscription", "tags": [ "webhooks" ] } }, "/v1/webhook-subscriptions/{id}": { "delete": { "description": "Tear down the subscription and stop further deliveries. Past `webhook_deliveries` rows are retained (audit trail) but no longer reachable via `/deliveries` once the parent row is gone.", "operationId": "delete_webhook_subscription", "responses": { "204": { "description": "Subscription removed." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No subscription with that id for this tenant." } }, "security": [ { "aerandil_oauth": [ "webhooks:write" ] } ], "summary": "Delete a webhook subscription", "tags": [ "webhooks" ] }, "get": { "description": "Read the current state of one subscription. Cross-tenant requests return `404` (indistinguishable from \"no such id\") to prevent enumeration.", "operationId": "get_webhook_subscription", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" } } }, "description": "Subscription state." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No subscription with that id for this tenant." } }, "security": [ { "aerandil_oauth": [ "webhooks:read" ] } ], "summary": "Get a webhook subscription", "tags": [ "webhooks" ] }, "parameters": [ { "description": "Subscription id.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "patch": { "description": "Patch the receiver `url`, `filter`, or `status`. Omitted fields stay as-is. Setting `status` to `active` is the reset path for a subscription that the worker pushed into `dead_letter` (the customer typically also advances `last_delivered_seq` out-of-band past the poison batch).", "operationId": "update_webhook_subscription", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookSubscriptionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" } } }, "description": "Updated subscription state." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No subscription with that id for this tenant." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation error — `invalid_url` or unknown fields." } }, "security": [ { "aerandil_oauth": [ "webhooks:write" ] } ], "summary": "Update a webhook subscription", "tags": [ "webhooks" ] } }, "/v1/webhook-subscriptions/{id}/deliveries": { "get": { "description": "Per-attempt audit of every delivery the worker made for one subscription, newest first. Each row records the seq range covered, attempt number, HTTP status (when the receiver answered), and a 512-byte response excerpt (the wire-level evidence operators need to debug a misbehaving receiver). \n\nUse this surface to root-cause a `dead_letter` subscription before resetting it — the run of failed attempts surfaces the receiver's last response shape.", "operationId": "list_webhook_deliveries", "parameters": [ { "description": "Page size. Default 50, server-clamps to 500.", "in": "query", "name": "limit", "required": false, "schema": { "maximum": 500, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWebhookDeliveriesResponse" } } }, "description": "Delivery audit for one subscription." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No subscription with that id for this tenant." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`invalid_limit` — `limit` must be positive." } }, "security": [ { "aerandil_oauth": [ "webhooks:read" ] } ], "summary": "List delivery attempts", "tags": [ "webhooks" ] }, "parameters": [ { "description": "Subscription id.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ] }, "/v1/webhook-subscriptions/{id}/promote-key": { "parameters": [ { "description": "Subscription id.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "Swap the secondary key into the primary slot and clear the secondary slot. The signal that the customer's rotation window is closing — from this point on, only the new key signs deliveries. \n\nNot idempotency-keyed: promote is naturally idempotent at the state level (after success, secondary is None, so a retry 422s with `no_secondary_key`).", "operationId": "promote_webhook_signing_key", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" } } }, "description": "Secondary promoted to primary. The returned `primary_key_fingerprint` is the old secondary's fingerprint." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No subscription with that id for this tenant." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "`no_secondary_key` — no rotation in progress; call `/rotate-key` first." } }, "security": [ { "aerandil_oauth": [ "webhooks:write" ] } ], "summary": "Promote the secondary signing key", "tags": [ "webhooks" ] } }, "/v1/webhook-subscriptions/{id}/rotate-key": { "parameters": [ { "description": "Subscription id.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "post": { "description": "Generate a fresh signing key into the **secondary** slot. Both keys are valid simultaneously — the worker emits one `v1=` signature per active key — so the customer can deploy receiver code that verifies under either while the rotation is in flight. \n\nReturns the new secondary key. Capture it now; subsequent reads expose only its fingerprint. \n\nOnce the new key is deployed end-to-end, call `/promote-key` to retire the old primary. \n\nIdempotent via `Idempotency-Key` so a network blip during step 1 doesn't double-rotate. A retry without the header generates a new secondary key (overwriting the previous one) — pass `Idempotency-Key` if a retry should replay rather than rotate again.", "operationId": "rotate_webhook_signing_key", "parameters": [ { "description": "Opaque idempotency token (Stripe-shape). Repeated POSTs with the same key replay the original response within the cache TTL rather than creating a duplicate object.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionWithKeyResponse" } } }, "description": "New secondary key emitted; primary unchanged." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "No subscription with that id for this tenant." } }, "security": [ { "aerandil_oauth": [ "webhooks:write" ] } ], "summary": "Rotate the signing key", "tags": [ "webhooks" ] } } }, "security": [ { "aerandil_oauth": [] } ], "servers": [ { "description": "Production API", "url": "https://api.aerandil.com" } ], "webhooks": { "aerandil_event_delivery": { "post": { "description": "**Aerandil sends this request** to every active subscription's receiver URL when one or more events past the subscription's `last_delivered_seq` match its filter. Stripe-shaped semantics: at-least-once delivery, exponential backoff on non-`2xx`, dead-letter after ~3 days, dual-key rotation. \n\n**Signature header.** `Aerandil-Signature: t=,v1=[,v1=]`. Verify with HMAC-SHA256 of `\"{t}.{raw_body}\"` against the subscription's signing key(s). Receivers MUST use a constant-time comparison and SHOULD reject envelopes whose `t` is older than 5 minutes (Stripe's published tolerance — replay protection). During a rotation window both the primary and the secondary key are valid; any `v1=` entry matching either key satisfies the contract. \n\n**Receiver contract.** Return `2xx` within 10 seconds. Any non-`2xx` (or no response) marks the batch failed and schedules a retry at `now + 60·2^n s + jitter(0..30s)`, capped at 24h, for up to 12 consecutive failures. After the 12th the subscription transitions to `dead_letter` and the worker stops attempting further deliveries until the operator resets it via `PATCH .../{id}` (and, typically, advances `last_delivered_seq` past the poison batch). \n\n**Idempotency.** The receiver MUST de-duplicate by the inner event `id` (which is the event-log `seq`); at-least- once means the same seq may arrive twice during a retry. \n\n**Batch shape.** A CloudEvents 1.0 envelope (`specversion`, `delivery_id`, `delivered_at`) carrying one or more event entries — see [`WebhookDeliveryBatch`]. Type strings follow the `aerandil.` namespace (e.g. `aerandil.object.created`, `aerandil.link.deleted`).", "operationId": "aerandil_event_delivery", "parameters": [ { "description": "HMAC-SHA256 signature envelope: `t=,v1=[,v1=]`. The signed payload is `\"{t}.{raw_body}\"`. Multiple `v1=` entries appear during a key-rotation window — any one valid signature satisfies the contract. Unknown chunks (e.g. a future `v2=`) MUST be ignored by the receiver for forward-compat.", "in": "header", "name": "Aerandil-Signature", "required": true, "schema": { "pattern": "^t=\\d+(,v1=[0-9a-f]+)+(,[^,]+)*$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryBatch" } } }, "description": "CloudEvents-shaped batch of events past the subscription's cursor (after filter narrowing).", "required": true }, "responses": { "200": { "description": "Receiver accepted the batch. Any 2xx status counts as success; Aerandil reads only the status code, never the response body (except for a 512-byte excerpt persisted to the delivery audit row)." }, "default": { "description": "Non-`2xx` (any status outside `200..=299`) — marks the delivery failed and triggers the exponential-backoff retry schedule. After 12 consecutive failures the subscription transitions to `dead_letter`." } }, "security": [ { "aerandil_webhook_signature": [] } ], "summary": "Deliver a batch of events (outbound)", "tags": [ "webhooks" ] } }, "aerandil_participant_dispatch": { "post": { "description": "**Aerandil sends this request** to a participant runner's configured HTTPS endpoint when a `participant_dispatch_attempt` row is claimed. The request body is a CloudEvents JSON-format envelope with `type = aerandil.participant_dispatch.dispatched`; the `data.dispatch_kind` and `dataschema` URI identify the specific work payload. \n\n**Signature.** The envelope carries `data.signature`, an Ed25519 detached signature over the RFC 8785 canonical envelope with `data.signature` elided. Receivers resolve `kid` against the coordinator signing key catalogue and reject missing, expired, or unverifiable envelopes. \n\n**Receiver contract.** Return any `2xx` to accept transport custody. `5xx`, `408`, `425`, `429`, and transport failures are retried under the dispatcher retry policy; other non-`2xx` statuses are terminal for that dispatch row. \n\n**Idempotency.** Deduplicate by the CloudEvents `id` plus `data.idempotency.idempotency_key`; retries reuse the same logical envelope id while stamping a fresh `time`.", "operationId": "aerandil_participant_dispatch", "requestBody": { "content": { "application/cloudevents+json": { "schema": { "$ref": "#/components/schemas/ParticipantDispatchDispatchedEnvelope" } } }, "description": "Coordinator-signed `dispatch` envelope (proposal 0022 §7.1).", "required": true }, "responses": { "200": { "description": "Receiver accepted the dispatch. Any `2xx` status counts as success; Aerandil reads only the status code." }, "default": { "description": "Non-`2xx` response. Retryable statuses follow proposal 0022 §11.2 (`5xx`, `408`, `425`, `429`); all other statuses are terminal." } }, "security": [], "summary": "Deliver a participant dispatch envelope (outbound)", "tags": [ "participant-dispatch" ] } }, "aerandil_participant_quarantine_notice": { "post": { "description": "**Aerandil sends this request** to participants affected by a federated-output quarantine. The request body is a CloudEvents JSON-format envelope with `type = aerandil.participant_dispatch.quarantine_notice`; `data.quarantine` identifies the output, incident, and operator follow-up actions. \n\n**Signature.** Same `data.signature` Ed25519 detached signature contract as participant dispatch envelopes. Receivers treat this as an authenticated coordinator notice, not as an OAuth-protected Aerandil API call. \n\n**Receiver contract.** Return any `2xx` after recording the notice locally. Non-`2xx` responses mean the participant has not accepted custody of the quarantine notice and may be retried by the emitting delivery path.", "operationId": "aerandil_participant_quarantine_notice", "requestBody": { "content": { "application/cloudevents+json": { "schema": { "$ref": "#/components/schemas/ParticipantDispatchQuarantineNoticeEnvelope" } } }, "description": "Coordinator-signed `quarantine_notice` envelope (proposal 0022 §7.5).", "required": true }, "responses": { "200": { "description": "Receiver accepted the quarantine notice. Any `2xx` status counts as success." }, "default": { "description": "Receiver did not accept the notice; the emitting delivery path decides whether to retry." } }, "security": [], "summary": "Notify a participant of a quarantine (outbound)", "tags": [ "participant-dispatch" ] } } } }